unalloc 0.2.2__tar.gz → 0.3.0__tar.gz

{unalloc-0.2.2 → unalloc-0.3.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.3.0 — 2026-10-04
+
+### Added
+- `report --json` carries a `provenance` block: unalloc version, window (live runs), alias-table digest, one entry per requested source with its status, payload SHA-256, byte count and row count, and a digest of the result body.
+- `report --keep-inputs DIR` writes the exact payloads the run parsed, named like the bundled fixtures, so the run can be replayed without the network.
+- `unalloc verify RESULT --inputs DIR` rebuilds a report from retained inputs. Exit 0 when it reproduces; 3 when an input is missing or its bytes changed at the same path; 4 when the inputs match but the result does not, naming a version or alias-table change; 5 when the recorded result does not conserve its own total.
+- Every command warns on stderr when the ledger is partial, naming each source that failed or had no input.
+- `Source.fetch_payload()` returns the raw provider payload; `fetch()` is now `parse(fetch_payload())` on the base class.
+
+### Fixed
+- A failed live source was printed to stderr and then dropped, so `report --json` gave no sign that its percentage covered only some sources. It is now recorded as `failed` in the provenance block.
+- With `--fixtures` and a missing fixture file, the "skipping" notice went to stdout and made `report --json` output invalid JSON. It goes to stderr.
+
+Attribution results are unchanged: every fixture report from 0.2.3 reproduces exactly.
+
+## 0.2.3 — 2026-09-21
+
+### Fixed
+- Figure 9's within-run spread is drawn as its own vertical bar rather than an error bar hung off the whole-run point. The old form had to clip whenever the whole-run share fell outside the window quartiles, which it does at three of the eight plotted points — the whole-run share is weighted by each window's traffic, so it need not lie inside the quartiles of its own windows.
+- §9 no longer presents the window statistics as a bootstrap confidence interval or as a bound on uncertainty. Consecutive windows of one run are not independent observations, so the paragraph now reports median, interquartile range and sign as descriptive statistics of that run, and the cross-reference matches what the figure actually draws. `bootstrap_ci` is renamed `resample_range`, and the metrics key `divergence_mean_ci95` becomes `divergence_mean_resample_range`.
+- arXiv kit refreshed against the built PDF: 14 pages, AI-use disclosure on page 13, and the concept DOI in the Comments field. The standalone abstract gained the synthetic-scenario qualification and the session-initial arrival-rate clarification that the paper's abstract already carried.
+
+### Added
+- `tests/test_paper_numbers.py` also checks the submission kit: the page, figure and table counts against the committed PDF, the concept DOI in both the kit and the paper, and the standalone abstract's length and scope wording.
+
 ## 0.2.2 — 2026-09-21
 
 ### Fixed

{unalloc-0.2.2 → unalloc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unalloc
-Version: 0.2.2
+Version: 0.3.0
 Summary: Find the AI spend nobody owns. Joins OpenCost allocation data with LLM provider bills and reports what's unattributed.
 Project-URL: Homepage, https://github.com/timurista/unalloc
 Project-URL: Issues, https://github.com/timurista/unalloc/issues
@@ -47,11 +47,11 @@ Description-Content-Type: text/markdown
 [![ci](https://github.com/timurista/unalloc/actions/workflows/ci.yml/badge.svg)](https://github.com/timurista/unalloc/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/timurista/unalloc/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://github.com/timurista/unalloc/blob/main/pyproject.toml)
-[![Paper](https://img.shields.io/badge/paper-PDF-1f5b45.svg)](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.24991-b31b1b.svg)](https://arxiv.org/abs/2609.24991)
 [![Explorer](https://img.shields.io/badge/explorer-live-1f5b45.svg)](https://timurista.github.io/unalloc/explorer.html)
 [![DOI](https://zenodo.org/badge/1368528624.svg)](https://doi.org/10.5281/zenodo.22761012)
 
-**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (PDF)](https://timurista.github.io/unalloc/paper/unalloc-case-studies.pdf), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
+**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
 
 OpenCost tells you what your Kubernetes workloads cost. Your provider dashboard tells you what your OpenAI and Anthropic calls cost. Getting both into one view is possible today — OpenCost has an OpenAI plugin — but the answer still depends on a join nobody checks: the same dollar can arrive through both your gateway and your provider bill, and the labels that say who owns it are set per workload, not per pod template. `unalloc` pulls all four sources into one normalized ledger, joins them on a label dimension you choose, and reports the number your finance team keeps asking for: how much of this month's AI spend can't be attributed to any team — and how much of the rest was only rescued by a fallback key.
 
@@ -167,6 +167,42 @@ Configure sources by environment variable:
 
 Restrict the run with `--source` to avoid double counting: if your traffic goes through LiteLLM, prefer `--source opencost --source litellm` and skip the direct provider adapters, since the same tokens appear in both. The [end-to-end case study](#case-studies-and-paper) measures exactly how much that costs you if you forget.
 
+## Reproducing a result
+
+A percentage that ends up in a finance deck will be questioned later, after the
+source data has moved on. A path is not enough to answer that: a fixture or an
+export can be rewritten under the same name, and a live billing API answers a
+re-run with today's data. So `report --json` carries a `provenance` block, and
+`--keep-inputs` retains the exact payloads it parsed:
+
+```bash
+unalloc report -D team --json --keep-inputs runs/2026-09/ > runs/2026-09.json
+unalloc verify runs/2026-09.json --inputs runs/2026-09/
+# reproduced: 73.5% unallocated of $66,630.38, result sha256:…
+```
+
+The provenance block records the unalloc version, the window (live runs only;
+fixtures carry their own dates), a digest of the label alias table, and one
+entry per requested source: its status, the SHA-256 of the payload bytes, and
+the rows it produced. A source that failed or had no input is recorded as
+`failed` or `missing` rather than dropped, and every command warns on stderr
+when the ledger is partial, because the percentage then covers the loaded
+sources only.
+
+`verify` exits with a code that says which boundary moved:
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Reproduced: same inputs, same result digest |
+| 3 | Cannot reconstruct: a retained input is missing, or its bytes changed |
+| 4 | Inputs match but the result differs: a rule or the tool changed in between |
+| 5 | The recorded result does not conserve its own total (a dollar counted twice or dropped) |
+
+A digest proves byte identity, not correctness. It cannot tell you a meter was
+accurate or a rule was fair, and it can only rebuild a result when the bytes
+it names were kept. Retained payloads contain your billing data; store them
+like the invoices they came from.
+
 ## How it works
 
 ```
@@ -193,7 +229,7 @@ Two design choices worth calling out:
 
 ## Case studies and paper
 
-Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)**. For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
+Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[Who Pays for the KV Cache? (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991)**, a preprint that has not been peer reviewed. The PDF built from this repository is at [paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf). For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
 
 | Study | What runs | Headline |
 | --- | --- | --- |
@@ -245,6 +281,7 @@ What `unalloc` does is narrower: read all four sources yourself — OpenCost, a
 - [ ] Per-feature unit economics using the `quantity`/`unit` fields already carried on `CostRow`
 - [ ] Azure OpenAI and Bedrock adapters
 - [x] `--budget` mode: exit non-zero when unallocated share crosses a threshold, for CI
+- [x] Result provenance and `unalloc verify`: rebuild an earlier report from retained inputs, or say why it can't be
 - [ ] `--exclude label=value` on a source, so gateway traffic can be dropped from provider billing instead of whole sources
 - [ ] Warn when distinct raw label keys collide on one canonical key
 
@@ -259,16 +296,31 @@ ruff check . && pytest
 
 ## Citing
 
-If you use unalloc or its case studies, please cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
+If you use the findings, please cite the paper, a preprint on arXiv ([arXiv:2609.24991](https://arxiv.org/abs/2609.24991), cs.DC):
+
+```bibtex
+@misc{urista_kvcache_2026,
+  author        = {Urista, Timothy},
+  title         = {Who Pays for the {KV} Cache? Attributing Shared {AI} Inference Spend Across {Kubernetes} and {LLM} Provider Bills},
+  year          = {2026},
+  eprint        = {2609.24991},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.DC},
+  doi           = {10.48550/arXiv.2609.24991},
+  url           = {https://arxiv.org/abs/2609.24991}
+}
+```
+
+If you use the software itself, cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
 
-- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.2.2, the code the paper describes
+- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.3.0. The paper describes 0.2.3; 0.3.0 adds result provenance and `unalloc verify` and changes no attribution result
 - **Version 0.2.1:** [doi:10.5281/zenodo.22761013](https://doi.org/10.5281/zenodo.22761013)
 
 ```bibtex
 @software{urista_unalloc_2026,
   author  = {Urista, Timothy},
   title   = {unalloc: find the AI spend nobody owns},
-  version = {0.2.2},
+  version = {0.3.0},
   year    = {2026},
   doi     = {10.5281/zenodo.22761012},
   url     = {https://github.com/timurista/unalloc}

{unalloc-0.2.2 → unalloc-0.3.0}/README.md

@@ -5,11 +5,11 @@
 [![ci](https://github.com/timurista/unalloc/actions/workflows/ci.yml/badge.svg)](https://github.com/timurista/unalloc/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/timurista/unalloc/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://github.com/timurista/unalloc/blob/main/pyproject.toml)
-[![Paper](https://img.shields.io/badge/paper-PDF-1f5b45.svg)](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.24991-b31b1b.svg)](https://arxiv.org/abs/2609.24991)
 [![Explorer](https://img.shields.io/badge/explorer-live-1f5b45.svg)](https://timurista.github.io/unalloc/explorer.html)
 [![DOI](https://zenodo.org/badge/1368528624.svg)](https://doi.org/10.5281/zenodo.22761012)
 
-**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (PDF)](https://timurista.github.io/unalloc/paper/unalloc-case-studies.pdf), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
+**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
 
 OpenCost tells you what your Kubernetes workloads cost. Your provider dashboard tells you what your OpenAI and Anthropic calls cost. Getting both into one view is possible today — OpenCost has an OpenAI plugin — but the answer still depends on a join nobody checks: the same dollar can arrive through both your gateway and your provider bill, and the labels that say who owns it are set per workload, not per pod template. `unalloc` pulls all four sources into one normalized ledger, joins them on a label dimension you choose, and reports the number your finance team keeps asking for: how much of this month's AI spend can't be attributed to any team — and how much of the rest was only rescued by a fallback key.
 
@@ -125,6 +125,42 @@ Configure sources by environment variable:
 
 Restrict the run with `--source` to avoid double counting: if your traffic goes through LiteLLM, prefer `--source opencost --source litellm` and skip the direct provider adapters, since the same tokens appear in both. The [end-to-end case study](#case-studies-and-paper) measures exactly how much that costs you if you forget.
 
+## Reproducing a result
+
+A percentage that ends up in a finance deck will be questioned later, after the
+source data has moved on. A path is not enough to answer that: a fixture or an
+export can be rewritten under the same name, and a live billing API answers a
+re-run with today's data. So `report --json` carries a `provenance` block, and
+`--keep-inputs` retains the exact payloads it parsed:
+
+```bash
+unalloc report -D team --json --keep-inputs runs/2026-09/ > runs/2026-09.json
+unalloc verify runs/2026-09.json --inputs runs/2026-09/
+# reproduced: 73.5% unallocated of $66,630.38, result sha256:…
+```
+
+The provenance block records the unalloc version, the window (live runs only;
+fixtures carry their own dates), a digest of the label alias table, and one
+entry per requested source: its status, the SHA-256 of the payload bytes, and
+the rows it produced. A source that failed or had no input is recorded as
+`failed` or `missing` rather than dropped, and every command warns on stderr
+when the ledger is partial, because the percentage then covers the loaded
+sources only.
+
+`verify` exits with a code that says which boundary moved:
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Reproduced: same inputs, same result digest |
+| 3 | Cannot reconstruct: a retained input is missing, or its bytes changed |
+| 4 | Inputs match but the result differs: a rule or the tool changed in between |
+| 5 | The recorded result does not conserve its own total (a dollar counted twice or dropped) |
+
+A digest proves byte identity, not correctness. It cannot tell you a meter was
+accurate or a rule was fair, and it can only rebuild a result when the bytes
+it names were kept. Retained payloads contain your billing data; store them
+like the invoices they came from.
+
 ## How it works
 
 ```
@@ -151,7 +187,7 @@ Two design choices worth calling out:
 
 ## Case studies and paper
 
-Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)**. For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
+Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[Who Pays for the KV Cache? (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991)**, a preprint that has not been peer reviewed. The PDF built from this repository is at [paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf). For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
 
 | Study | What runs | Headline |
 | --- | --- | --- |
@@ -203,6 +239,7 @@ What `unalloc` does is narrower: read all four sources yourself — OpenCost, a
 - [ ] Per-feature unit economics using the `quantity`/`unit` fields already carried on `CostRow`
 - [ ] Azure OpenAI and Bedrock adapters
 - [x] `--budget` mode: exit non-zero when unallocated share crosses a threshold, for CI
+- [x] Result provenance and `unalloc verify`: rebuild an earlier report from retained inputs, or say why it can't be
 - [ ] `--exclude label=value` on a source, so gateway traffic can be dropped from provider billing instead of whole sources
 - [ ] Warn when distinct raw label keys collide on one canonical key
 
@@ -217,16 +254,31 @@ ruff check . && pytest
 
 ## Citing
 
-If you use unalloc or its case studies, please cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
+If you use the findings, please cite the paper, a preprint on arXiv ([arXiv:2609.24991](https://arxiv.org/abs/2609.24991), cs.DC):
+
+```bibtex
+@misc{urista_kvcache_2026,
+  author        = {Urista, Timothy},
+  title         = {Who Pays for the {KV} Cache? Attributing Shared {AI} Inference Spend Across {Kubernetes} and {LLM} Provider Bills},
+  year          = {2026},
+  eprint        = {2609.24991},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.DC},
+  doi           = {10.48550/arXiv.2609.24991},
+  url           = {https://arxiv.org/abs/2609.24991}
+}
+```
+
+If you use the software itself, cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
 
-- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.2.2, the code the paper describes
+- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.3.0. The paper describes 0.2.3; 0.3.0 adds result provenance and `unalloc verify` and changes no attribution result
 - **Version 0.2.1:** [doi:10.5281/zenodo.22761013](https://doi.org/10.5281/zenodo.22761013)
 
 ```bibtex
 @software{urista_unalloc_2026,
   author  = {Urista, Timothy},
   title   = {unalloc: find the AI spend nobody owns},
-  version = {0.2.2},
+  version = {0.3.0},
   year    = {2026},
   doi     = {10.5281/zenodo.22761012},
   url     = {https://github.com/timurista/unalloc}

{unalloc-0.2.2 → unalloc-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unalloc"
-version = "0.2.2"
+version = "0.3.0"
 description = "Find the AI spend nobody owns. Joins OpenCost allocation data with LLM provider bills and reports what's unattributed."
 readme = "README.md"
 requires-python = ">=3.11"

{unalloc-0.2.2 → unalloc-0.3.0}/src/unalloc/__init__.py

@@ -2,5 +2,5 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 __all__ = ["__version__"]