clausius 0.1.0__tar.gz

clausius-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# The measurement corpus IS the differentiated asset and is published:
+#   records/frontier, records/regress, records/context  (~5 MB, 159 files)
+# Everything else under records/ is a 6 GB pile of LoRA adapters, training
+# corpora and routing traces — derivable, huge, and not what anyone needs.
+records/*
+!records/frontier/
+!records/regress/
+!records/context/
+!records/quantladder/
+!records/backend/
+*.jsonl.gz
+*.safetensors
+*.npy
+
+# scratch
+*.log
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.DS_Store
+.obsidian/
+.pytest_cache/
+*.egg-info/
+dist/
+build/

clausius-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

clausius-0.1.0/NOTICE

@@ -0,0 +1,48 @@
+clausius
+Copyright 2026 Beata Kouchnir
+
+This product includes software developed for measuring the effect of
+deployment-time changes on language models.
+
+The research package (`knowledge/`) vendors code under `knowledge/_vendor/`,
+copied from the author's other work rather than depended on, so that this
+repository is self-contained. It carries the same license as the rest.
+
+--------------------------------------------------------------------------
+DATASETS
+
+The measurement corpus under `records/` holds results DERIVED from the public
+evaluation datasets below — accuracy, entropy and per-item scores. No dataset
+is bundled: `knowledge/` fetches each one from the Hugging Face Hub at run
+time, so reproducing an experiment means obtaining the data from its original
+source under that source's own terms.
+
+    GSM8K            openai/gsm8k                              MIT
+    MMLU-Pro         TIGER-Lab/MMLU-Pro                        MIT
+    PopQA            akariasai/popqa                           no license declared
+    HumanEval+       evalplus/humanevalplus                    Apache-2.0
+    IFEval           google/IFEval                             Apache-2.0
+    GPQA             Idavidrein/gpqa                           CC BY 4.0, gated
+    AA-Omniscience   ArtificialAnalysis/AA-Omniscience-Public  Apache-2.0
+    HLE              cais/hle                                  MIT, gated
+
+Two files redistribute source items verbatim, under the MIT terms above:
+
+    records/quantladder/prompts.gsm8k100.jsonl   100 GSM8K questions
+    records/quantladder/prompts.gsm8k200.jsonl   200 GSM8K questions
+
+and the gold answers for those items are stored alongside the model's
+predictions in `records/quantladder/acc.*.json`. They are included so that the
+same-item comparison in FINDINGS F14c can be checked exactly rather than
+approximately.
+
+GPQA is treated differently, at its authors' request: they ask that the
+dataset not be posted in plain text online, to keep it out of future training
+corpora. No GPQA question, answer option or gold answer appears anywhere in
+this repository, and the model's generated answer text was removed from
+`records/stage_a.gpqa*.json` for the same reason. What remains is derived
+measurement — correctness, entropy, and the domain label.
+
+IFEval scoring uses Google Research's `instruction_following_eval` registry
+(Apache-2.0), which is NOT bundled here. Where it is absent the scorer returns
+no verdict for that item rather than guessing.

clausius-0.1.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: clausius
+Version: 0.1.0
+Summary: Detect whether a deployment change degraded your model — without a labeled eval set
+Project-URL: Homepage, https://github.com/beatakouchnir/clausius
+Project-URL: Findings, https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md
+Project-URL: Issues, https://github.com/beatakouchnir/clausius/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: llm,mixture-of-experts,mlx,quantization,regression-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.20; extra == 'mlx'
+Description-Content-Type: text/markdown
+
+# clausius — did the thing you changed break your model?
+
+Two questions, both answered on consumer hardware (M5 Max, 128 GB), across five
+model families:
+
+1. **What is the best model you can actually run in the memory you have?**
+2. **If you change anything — config, quantization, fine-tune — how would you
+   know it broke the model, without a labeled eval set?**
+
+## What's new here
+
+- **Accuracy measured across MoE offload configurations at all** — four surveyed
+  implementations report none. It inverts the default advice: at matched memory,
+  aggressive quantization costs **73 points** of instruction adherence where
+  exact expert offload costs **1.0**.
+- **Label-free regression detection, checked against independently measured
+  damage.** Predictive entropy is well studied; using it to detect that *a
+  deployment change broke the model* — validated against five unrelated damage
+  mechanisms whose true cost was measured separately — appears not to be. It
+  flagged a −2.2pp quantization regression on **60 unlabeled prompts**, where
+  paired McNemar on gold labels needed **n=878** to reach p<0.05 (F14).
+- **The corpus is committed, so the tables below rebuild on a laptop** — no
+  model, no accelerator, two commands. Negatives included: eight controlled
+  failures where the interesting signal lost to a simpler one, and seven places
+  where a result did not survive its own check and the record says so.
+
+**Scope, up front.** Capturing needs Apple Silicon (`mlx-lm`). Everything else —
+`compare`, the analysis, and re-deriving every table below from the committed
+corpus — is pure numpy and runs anywhere, with no model downloads:
+
+```bash
+git clone https://github.com/beatakouchnir/clausius && cd clausius
+pip install ".[dev]" && pytest -q                  # 36 tests, no accelerator
+python -m knowledge.quantladder analyze            # rebuilds F14's ladder from records
+python -m knowledge.frontier report                # rebuilds the 3-axis Pareto frontier
+```
+
+That is the fastest way to check whether the numbers here are real.
+
+---
+
+*Named for Rudolf Clausius, who coined the word **entropy** in 1865 — from the
+Greek `trope`, transformation, shaped to echo "energy" so the two would sound
+like the related quantities they are. Entropy is the signal this tool reads.*
+
+## Quickstart
+
+```bash
+pip install "clausius[mlx] @ git+https://github.com/beatakouchnir/clausius"
+```
+
+Take 60 prompts of your own — production traffic is ideal, and **no labels are
+needed** — or start with the 60 in [`examples/prompts.jsonl`](https://github.com/beatakouchnir/clausius/blob/main/examples/prompts.jsonl).
+Capture the configuration you trust, capture the one you changed, compare:
+
+```bash
+clausius capture --model ./gemma-26b-a4b-4bit --prompts examples/prompts.jsonl \
+    --out ref.json  --max-tokens 1536
+clausius capture --model ./gemma-26b-a4b-2bit --prompts examples/prompts.jsonl \
+    --out cand.json --max-tokens 1536
+clausius compare ref.json cand.json --show 3
+```
+
+```
+REGRESSION  (max d_z = +5.922, threshold 0.3, one-sided)
+  compared 20 paired items, dropped 5 truncated
+  all signals: max +5.92  p90 +11.64  mean +10.43  mean_top10 +9.00  first +2.80  gen_len +10.55
+```
+
+That is a real run, on 25 unlabeled prompts. The two checkpoints differ only in
+quantization; the 2-bit one independently measures **73 points lower** on
+instruction adherence. `compare` exits non-zero on a regression, so it drops
+into CI without glue.
+
+**→ [USAGE.md](https://github.com/beatakouchnir/clausius/blob/main/USAGE.md) is the operating manual**: choosing prompts, setting
+the token cap, reading `d_z` and its interval, calibrating your own null, and
+running it as a CI gate. Start there after your first run.
+
+**Every default is a measured result, not a preference** — the 0.3 threshold
+comes from 13 configurations known to be harmless, the one-sided test from a
+construction that fools a two-sided one, the truncation filter from an effect
+that doubles once you apply it. `src/clausius/core.py` states each one and
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md) has the evidence.
+
+> **Status.** `clausius` is installable and tested (36 tests, no accelerator
+> required). The `knowledge/` research package that produced the findings is
+> *not* packaged — it needs local model checkpoints and an external artifact
+> store, and is kept for reproducibility rather than reuse.
+
+---
+
+## What was measured
+
+Full evidence, positives *and* negatives, in
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md) —
+which opens with a prior-art accounting stating which parts independently
+re-derive published work and which appear to be new. The headline results:
+
+| | result | where |
+|---|---|---|
+| **Offload beats downsizing** | an offloaded 35B at **3.40 GB** scores **0.9447** on gsm8k, against a natively-fitting 4B at 3.91 GB scoring 0.8426. Same ordering on popqa (+13.9pp) and mmlu_pro (+20.9pp). The whole cost is latency. | F3–F6 |
+| **The lossy shortcut is dominated** | *dropping* non-resident experts instead of fetching them costs **91% of gsm8k accuracy** at 50% residency, while being slower. | F6 |
+| **Label-free detection works** | validated against five unrelated damage mechanisms whose true damage was measured independently. Benign controls stay clean: a 3.3× memory reduction changes ~25% of generations textually and moves no signal. | F8 |
+| **It is more sensitive than labels** | the −2.2pp regression above: flagged on 60 unlabeled prompts, where labels needed n=878. | F14 |
+| **Forgetting is detectable too** | move the reference and it becomes a training monitor: LoRA checkpoints on a held-out domain read d_z +0.74 to +0.84 at −16 to −26pp accuracy. | F9 |
+| **Short benchmarks understate damage ~14×** | factual QA loses 1.5pp where structured generation loses 18–21pp under the same quantization — the axis agents live on. | F11 |
+| **Routing carries a fact-level address** | ablate the experts a fact routes to and that fact degrades far more than a paraphrase, a same-relation fact, or a random control. Two architectures. A **mechanism** result, not a product. | R9–R10 |
+
+### What it does not do
+
+- **Sensitivity is the weaker half.** Specificity is 13/13; a −5.7pp config is
+  missed at any threshold that preserves that record.
+- **Confidence-increasing damage would be invisible** to a one-sided detector.
+  Three mechanisms were built to produce it and none did, but it is not excluded.
+- **d_z is ordinal, not proportional.** 3-bit loses 25× more accuracy than 4-bit
+  and reads 2× the d_z. "Something moved, and roughly how hard" is supportable;
+  "you lost k accuracy points" is not.
+- Needs logits and a reference config; it cannot score a config in isolation.
+- **The threshold is calibrated on one stack.** On a different framework, device
+  or quantizer, measure your own null first —
+  [USAGE.md](https://github.com/beatakouchnir/clausius/blob/main/USAGE.md#calibrating-your-own-null) has the recipe.
+
+### Scope: local models, GPU capture
+
+**Local and self-hosted only, deliberately.** Anthropic exposes no logprobs at
+all, Gemini's are missing on current frontier models, and OpenAI caps
+`top_logprobs` at 20 — *truncated* entropy, a different quantity. Hosted-API
+support and cascade routing are recorded as **don't-build** decisions in
+[EXPERIMENT.md](https://github.com/beatakouchnir/clausius/blob/main/EXPERIMENT.md).
+
+**Capture targets a GPU**: Apple Silicon via MLX in this release, CUDA next,
+CPU never — measured here, 7B decode runs 6.7 tok/s on CPU against 22 on the
+same machine's GPU, the gap widens with size, and the 26B MoE behind the
+findings is impractical there. Two terms that are often conflated:
+
+| | | |
+|---|---|---|
+| **framework** | mlx, PyTorch | which library runs the forward pass |
+| **device** | cuda, mps, cpu | which hardware PyTorch dispatches to |
+
+Nothing about the *method* needs Apple Silicon, and a working PyTorch framework
+backend exists on the `feat/torch-backend` branch — **deliberately not
+shipped**. It was measured on mps and cpu (F15, F15c), so the framework path is
+exercised; what has never been calibrated is the **cuda device** and the
+CUDA-native quantizers (bitsandbytes, GPTQ, AWQ). Shipping a runtime whose
+threshold is uncalibrated on the device most users would run would contradict
+the claim this package makes about its defaults. The bar it must clear is in
+[EXPERIMENT.md](https://github.com/beatakouchnir/clausius/blob/main/EXPERIMENT.md).
+
+## Claim taxonomy — keep these separate
+
+Two halves making **different kinds of claim**. Conflating them would overstate
+one and undersell the other.
+
+| half | signal | claim type | validated by | breadth |
+|---|---|---|---|---|
+| **online** | predictive entropy | *"this answer is likely wrong"*, *"this change broke the model"* — a **correctness** claim | Stages A–D, F8–F9 | 5 models, 6 task configs, 5 damage mechanisms |
+| **offline** | routing ablation | *"this came from stored fact X"* — a **mechanism** claim | R3, R9, R9c, R10 | 2 architectures, probe-style |
+
+**Entropy is mechanism-blind** — it reports that the model was uncertain, not
+*how* the answer was produced. So *"flag the answers the model was least sure
+of"* is defensible and *"our telemetry tells you how the answer was generated"*
+is not. **Neither half claims to improve accuracy.**
+
+## What did not work
+
+Eight controlled negatives where routing lost to a simpler signal — usually
+reading the prompt text, or predictive entropy. The structural reason: routing
+is downstream of the residual stream *and* the prompt, so it is bounded by
+both. Part II of
+[FINDINGS.md](https://github.com/beatakouchnir/clausius/blob/main/FINDINGS.md)
+records them so they are not re-run.
+
+## Seven corrections worth reading
+
+The record keeps its own failures, because they were load-bearing:
+
+- **A planned 16-50 GPU-hour sweep was canceled after reading the
+  implementation.** `policy='exact'` fetches missing experts before computing —
+  it would have measured a guaranteed flat line.
+- **A confident mechanistic hypothesis died with its own bug fix.** A tidy
+  shared-expert explanation for a gemma-vs-qwen top-k split evaporated when a
+  ranking error was corrected — `argpartition` guarantees membership, not order.
+- **An instrumentation bug meant a whole axis was never measured.**
+  `mx.get_peak_memory()` captured the model load before the cache freed it, so
+  every configuration reported identical memory.
+- **A published-looking result was a scoring artifact.** The RAG conditional
+  claim read −0.431 in the predicted direction until the scorer accepted any
+  gold alias; it then read +0.066, the wrong direction. Recorded as open.
+- **A rationale in the shipped code was wrong for three runs running.** The
+  truncation filter was justified by "a damaged model rambles into the token
+  cap" — but a *healthy* 4-bit truncated 47/60 items at cap 512 where a
+  destroyed 2-bit truncated 3, and two LoRA fine-tunes truncated 22 and 33 of 50
+  where their base truncated none. Rambling tracks off-distribution, not damage.
+  The filter was right; the reason was not (F14b).
+- **A calibration claim was falsified by the next measurement.** A widened null
+  (+0.172) was attributed to the reference being unquantized; the same pair
+  reads −0.062 on gsm8k. It was the prompt set. Superseded, not overwritten
+  (F14c).
+- **An assumption made the exact error the finding warns against.** F14 assumed
+  3-bit "sits between two measured points in damage" — right about the ordering,
+  badly wrong about the distance: −56.6pp, a broken deployment, at only 2x
+  4-bit's d_z. Kept visible as a worked example of ordinal-not-proportional
+  (F14d).
+
+Two method rules came out of them, applied throughout:
+
+> **Read a knob's implementation before scoping a sweep over it.**
+> **A wiring control must be able to fail on the assumption it protects.**
+
+The second has teeth: a top-k no-op control passed 16/16 while the ranking
+assumption beneath it was wrong, because keeping every position is
+order-independent.
+
+## Prior art
+
+Applied, not ours: MoE expert offloading with an LRU cache
+([Mixtral-offloading](https://arxiv.org/pdf/2312.17238)), speculative expert
+prefetch ([HOBBIT](https://arxiv.org/pdf/2411.01433), ExpertFlow, CommitMoE),
+predictive entropy, McNemar, Belady, Pareto dominance.
+
+What appears new: **accuracy measured across MoE offload configurations at
+all** (four surveyed implementations report none); exact offload being
+**capacity-non-reproducible but fixed-capacity deterministic**, which
+invalidates output-diffing as a validation method; **prefill admitting *optimal*
+caching**, since a layer's routing for the whole prompt yields the access
+sequence before any fetch; and **label-free config-regression detection
+validated against independently-known damage**.
+
+---
+
+## Repository layout
+
+| path | what | needs |
+|---|---|---|
+| `src/clausius/` | **the tool** — capture, compare, CLI | numpy; mlx-lm only to capture |
+| `tests/` | 36 tests, none load a model; CI installs the built wheel | numpy |
+| `records/` | **the measurement corpus** — the evidence behind FINDINGS.md, ~10 MB | — |
+| `knowledge/` | the research package that produced the findings | local checkpoints, external artifact store (`CLAUSIUS_ARTIFACTS`) |
+| `USAGE.md` | **the operating manual** — prompts, caps, reading the output, CI | — |
+| `FINDINGS.md` | the full experimental record, positives and negatives | — |
+| `EXPERIMENT.md` | designs, scope decisions, what was deliberately not built, and ten hard-won operational cautions | — |
+
+The split is deliberate: the detector **needs no labels and no benchmark harness
+to be used** — scoring exists only to *validate* it, which is what `knowledge/`
+does ([its README](https://github.com/beatakouchnir/clausius/blob/main/knowledge/README.md)
+documents every module and how to obtain the datasets). Analysis is stdlib/numpy
+and loads no model, deliberately: MLX uses unified memory, so pinning to
+`mx.cpu` isolates nothing — the axis that matters is loads-a-model vs doesn't.