From 8a48cb83d0a789928b3d1298244b3348e7fa3d9a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Aug 2026 23:56:47 +0000 Subject: [PATCH 01/18] docs: add source-linked adoption census Adds doc/adoption-census.md, a versioned inventory of documented libCacheSim adoption. Every entry records the artifact, a verbatim quote showing libCacheSim use, a source URL, the verification date, and a confidence grade. Contents of census v1.0.0 (snapshot 2026-08-12): - 5 confirmed direct users (PolicySmith, 3L-Cache, DynamicAdaptiveClimb, SCION, CacheBench), 4 of which are independent of the upstream project - distribution and repository signals (GitHub, PyPI, npm) - self-reported aggregate claims, graded and attributed rather than asserted as fact - algorithm-lineage adoption (S3-FIFO/SIEVE) kept strictly separate from simulator adoption - candidates that were checked and excluded, so future revisions do not re-investigate the same dead ends Also documents the census methodology, its known limitations, and the update protocol, and links the document from both README indexes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- README.md | 7 + doc/README.md | 3 + doc/adoption-census.md | 290 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 300 insertions(+) create mode 100644 doc/adoption-census.md diff --git a/README.md b/README.md index a518e2f7..46fe857c 100644 --- a/README.md +++ b/README.md @@ -379,6 +379,13 @@ We provide a more comprehensive cache datasets at [https://github.com/cacheMon/c +--- +## Who uses libCacheSim +See the [adoption census](/doc/adoption-census.md) for a source-linked inventory of documented +libCacheSim adoption — research artifacts built on it, distribution channels, and downstream +adoption of algorithms designed in it. Every entry carries its evidence, source URL, verification +date, and confidence grade. + --- ## Contributions We gladly welcome pull requests. diff --git a/doc/README.md b/doc/README.md index b95f8072..b05465ca 100644 --- a/doc/README.md +++ b/doc/README.md @@ -18,3 +18,6 @@ ## Developer Documentation - [Debugging Guide](debug.md) - [Install & Build](install.md) + +## Project +- [Adoption Census](adoption-census.md) — source-linked inventory of documented libCacheSim adoption diff --git a/doc/adoption-census.md b/doc/adoption-census.md new file mode 100644 index 00000000..6bf1db85 --- /dev/null +++ b/doc/adoption-census.md @@ -0,0 +1,290 @@ +# libCacheSim Adoption Census + +**Census version:** 1.0.0 +**Snapshot date:** 2026-08-12 +**Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) + +A source-linked inventory of documented libCacheSim adoption. Every entry below carries a +public URL, the quoted evidence that supports it, the date the evidence was checked, and a +confidence grade. Entries that could not be verified are recorded as such rather than dropped +silently, and claims that were checked and found to be false are listed in +[Checked and excluded](#6-checked-and-excluded). + +This document is versioned with the source tree, so any commit of this file is a citable +snapshot. See [How to cite this census](#how-to-cite-this-census). + +--- + +## 1. Methodology + +### What counts as adoption + +An entry qualifies as **direct adoption** only if a public artifact shows libCacheSim itself +being built on, forked, linked, or executed — not merely cited in a bibliography. Papers that +list libCacheSim as related work without using it are excluded. + +Adoption of *algorithms designed and evaluated in libCacheSim* (S3-FIFO, SIEVE, QD-LP) is +tracked separately in [Section 5](#5-algorithm-lineage-not-libcachesim-adoption). A system that +implements SIEVE is **not** a libCacheSim user. Conflating the two would inflate this census by +an order of magnitude, and the distinction is the single most important integrity rule here. + +### Confidence grades + +| Grade | Meaning | +| --- | --- | +| **A** | Primary source, quoted verbatim, states use of libCacheSim unambiguously. | +| **B** | Primary source confirms the relationship, but the extent of use is inferred. | +| **C** | Self-reported or aggregate claim with no public per-entry roster to audit. | +| **U** | Lead identified but not verifiable by automated fetch; retained for manual follow-up. | + +### Verification protocol + +Each source URL was fetched and read on the verification date shown. Where a source is a PDF, +the full text was searched for `libCacheSim` / `libcachesim` before the entry was accepted. Two +candidate papers surfaced by search engines were rejected this way (Section 6). + +### Known limitations + +1. **No GitHub-wide code search was performed.** This session's tooling was scoped to the + libCacheSim repository, so source-level forks and vendored copies across GitHub are + undercounted. A future revision run with repository-search access should add a + `code search: "libCacheSim" in build files` pass — this is the largest known gap. +2. **Package dependency graphs miss this ecosystem.** libCacheSim is typically consumed by + building from source or forking, not by declaring a dependency. GitHub's dependency graph for + the Python binding reported **0 repositories and 0 packages** on 2026-08-12 + ([source](https://github.com/cacheMon/libCacheSim-python/network/dependents)) — a measured + negative, not an absence of users. Treat dependent counts as a floor of zero information. +3. **Private and industrial use is invisible.** Commercial users appear here only if they publish. + The aggregate figures in [Section 4](#4-self-reported-aggregate-claims) exist precisely because + that population is not publicly enumerable. +4. **Download statistics are absent.** pypistats.org returned HTTP 429 during this snapshot; PyPI + download counts should be added in the next revision. + +--- + +## 2. Distribution and repository signals + +Measured facts about how libCacheSim is published and consumed. All figures fetched 2026-08-12. + +| Signal | Value | Source | Grade | +| --- | --- | --- | --- | +| GitHub stars | 339 | [github.com/1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) | A | +| GitHub forks | 111 | [github.com/1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) | A | +| PyPI package | `libcachesim`, latest `0.3.3.post4` released 2026-02-17; 5 released versions; requires Python >=3.10; GPLv3+ | [pypi.org/project/libcachesim](https://pypi.org/project/libcachesim/) · [JSON API](https://pypi.org/pypi/libcachesim/json) | A | +| PyPI maintainers | `1a1a11a`, `hxia7` | [pypi.org/project/libcachesim](https://pypi.org/project/libcachesim/) | A | +| npm package | `libcachesim-node`, latest `0.3.2`; first published 2025-06-18, latest 2025-07-14; MIT | [registry.npmjs.org/libcachesim-node](https://registry.npmjs.org/libcachesim-node) | A | +| Python binding repo | [cacheMon/libCacheSim-python](https://github.com/cacheMon/libCacheSim-python), docs at [cachemon.github.io/libCacheSim-python](https://cachemon.github.io/libCacheSim-python/) | [pypi.org/project/libcachesim](https://pypi.org/project/libcachesim/) | A | +| Dependency-graph dependents (Python binding) | 0 repositories, 0 packages | [dependents graph](https://github.com/cacheMon/libCacheSim-python/network/dependents) | A | + +Star and fork counts are point-in-time and will drift; re-measure rather than citing these +numbers as current. + +--- + +## 3. Confirmed direct users + +Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. + +### 3.1 PolicySmith — LLM-generated cache policies (UT Austin) + +- **Artifact:** *Man-Made Heuristics Are Dead. Long Live Code Generators!*, + [arXiv:2510.08803](https://arxiv.org/abs/2510.08803) (2025-10-13). Dwivedula, Saxena, Akella, + Chaudhuri, Kim. +- **Evidence (quoted):** "Our prototype is built on libCacheSim, a high-performance web cache + simulator with an event-driven interface." ([full text](https://arxiv.org/html/2510.08803v1)) +- **Use:** libCacheSim is the execution substrate for evaluating LLM-generated eviction + heuristics against established baselines. +- **Code:** [github.com/ldos-project/policysmith](https://github.com/ldos-project/policysmith) +- **Grade:** A · **Independent of upstream:** yes + +### 3.2 3L-Cache — FAST '25 (learning-based eviction) + +- **Artifact:** *3L-Cache: Low Overhead and Precise Learning-based Eviction Policy for Caches*, + USENIX FAST '25 ([program page](https://www.usenix.org/conference/fast25/presentation/zhou-wenbin)). + Artifact repository: [github.com/optiq-lab/3L-Cache](https://github.com/optiq-lab/3L-Cache). +- **Evidence (quoted):** "3L-Cache is implemented in the libCacheSim library, and its experimental + environment configuration is consistent with libCacheSim." The repository layout is annotated + "3L-Cache/ -- Forked from LibCacheSim, which is a platform for cache evaluation." +- **Use:** Whole-project fork of libCacheSim used as the evaluation platform (reported 4855 traces, + twelve comparison policies). +- **Upstreamed:** tracked in [issue #119](https://github.com/1a1a11a/libCacheSim/issues/119) + (opened 2025-01-23, closed 2025-02-20); the algorithm now ships in-tree at + [`libCacheSim/cache/eviction/3LCache/`](../libCacheSim/cache/eviction/3LCache/). +- **Grade:** A · **Independent of upstream:** yes (fork authored externally; integration by upstream) + +### 3.3 DynamicAdaptiveClimb (Ben-Gurion University et al.) + +- **Artifact:** *DynamicAdaptiveClimb: Adaptive Cache Replacement with Dynamic Resizing*, + [arXiv:2511.21235v1](https://arxiv.org/abs/2511.21235) (2025-11-26). Berend, Dolev, Kumari, + Mishra, Kogan-Sadetsky, Somani. +- **Evidence (quoted):** "We conduct all evaluations using libCacheSim, an open-source, + high-performance, and extensible cache simulator widely adopted in recent caching research." + ([full text](https://arxiv.org/html/2511.21235v1)) +- **Use:** All reported evaluation — 1067 traces across six datasets (Alibaba, TencentCBS, Wiki, + Twitter, MetaCDN, Meta KV), miss ratio and multi-threaded throughput, against thirteen policies. +- **Grade:** A · **Independent of upstream:** yes + +### 3.4 SCION (PingCAP) + +- **Artifact:** *SCION: Size-aware Policy Orchestration for Nonstationary Object Caches*, + [arXiv:2605.01055v1](https://arxiv.org/html/2605.01055) (2026-03-27). Qizhi Wang, PingCAP + Data & AI-Innovation Lab. +- **Evidence (quoted):** "We implement a trace-driven benchmark in C++ on top of libCacheSim." + The authors additionally report integrating AdaptiveClimb/DynamicAdaptiveClimb into libCacheSim + and building a trace conversion pipeline. +- **Use:** Benchmark harness over 30 public traces from `cache_dataset`, >5M requests each. +- **Grade:** A · **Independent of upstream:** yes (industrial affiliation, not an upstream maintainer) + +### 3.5 CacheBench (UCSC OSPO reproducibility program) + +- **Artifact:** *Midterm Report: Simulation, Comparison, and Conclusion of Cache Eviction*, + UCSC OSPO project report, 2025-08-06, Haocheng Xia (UIUC, visiting Harvard). + [Report](https://ucsc-ospo.github.io/report/osre25/harvard/cachebench/2025-08-06-haochengxia/) +- **Evidence (quoted):** "At the core of CacheBench lie two key components: the high-performance + cache simulator, libCacheSim" — users "run simulation analyses using libCacheSim and the cache + datasets." +- **Use:** libCacheSim is one of the two core components of a benchmarking suite built over the + open cache trace datasets. +- **Grade:** A · **Independent of upstream:** **no** — the author is also an upstream contributor + (closed [issue #119](https://github.com/1a1a11a/libCacheSim/issues/119)) and a PyPI maintainer of + the Python binding. Counted as affiliated use, not third-party validation. + +### Summary + +| Adopter | Type | Relationship | Grade | Independent | +| --- | --- | --- | --- | --- | +| PolicySmith (UT Austin) | Research prototype | Built on | A | Yes | +| 3L-Cache (FAST '25) | Research artifact | Fork, upstreamed | A | Yes | +| DynamicAdaptiveClimb | Research evaluation | All evaluation | A | Yes | +| SCION (PingCAP) | Industrial research | Benchmark on top of | A | Yes | +| CacheBench | Benchmark suite | Core component | A | No (affiliated) | + +Four of five confirmed direct users are independent of the upstream project. + +--- + +## 4. Self-reported aggregate claims + +These figures come from author-supplied biographies. They are consistent across two independent +hosts and across time, but no public roster backs them, so they cannot be audited entry by entry. +They are recorded as **Grade C** and should be attributed, not asserted as fact. + +| Claim (quoted) | Source | Date checked | Grade | +| --- | --- | --- | --- | +| "the open-source cache simulation library he created, libCacheSim, has been used by almost 100 research institutes and companies." | [junchengyang.com](https://junchengyang.com/) | 2026-08-12 | C | +| "the open-source cache simulation library libCacheSim he created has been used by close to 100 research institutes and companies." | [Georgia Tech SCS seminar announcement, 2024-04-16](https://ic.gatech.edu/events/2024/04/16/scs-faculty-candidate-seminar-juncheng-yang) | 2026-08-12 | C | + +The two statements agree in substance and differ only in wording ("almost" vs. "close to"), +across a roughly two-year span. Both trace to the same author, so they are one claim with two +publication venues, not two independent measurements. + +--- + +## 5. Algorithm lineage (not libCacheSim adoption) + +S3-FIFO and SIEVE were designed and evaluated in libCacheSim, and libCacheSim ships reference +implementations ([`S3FIFO.c`](../libCacheSim/cache/eviction/S3FIFO.c), +[`Sieve.c`](../libCacheSim/cache/eviction/Sieve.c)). Systems below adopted the **algorithms**. +They are recorded here because the lineage is real and traceable, and excluded from Section 3 +because implementing an algorithm is not using the simulator. + +### 5.1 Aggregate statements + +| Claim (quoted) | Source | Grade | +| --- | --- | --- | +| "S3-FIFO and SIEVE are adopted for production at Google, VMware, Redpanda, and several others, with over 60 open-source libraries and packages in 18 programming languages available on GitHub." | [junchengyang.com](https://junchengyang.com/) | C | +| "These algorithms have seen broad industry adoption — including in Android, the TiDB database, and many others — and have been implemented in dozens of open-source systems and libraries, including over 60 across more than 16 programming languages on GitHub." | [Harvard SEAS news, 2025-10-27](https://seas.harvard.edu/news/2025/10/juncheng-yang-winner-acm-award-dissertation-most-impact) | B | + +### 5.2 Named SIEVE adopters with direct source links + +From the SIEVE project's adopters list ([sievecache.com](https://sievecache.com/), which redirects +to [cachemon.github.io/SIEVE-website](https://cachemon.github.io/SIEVE-website/)), fetched +2026-08-12. Each entry below links to the specific implementing file or pull request, so each is +independently checkable. + +| System | Evidence link | +| --- | --- | +| immudb | [PR #1971](https://github.com/codenotary/immudb/pull/1971) | +| TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/master/pkg/infoschema/sieve.go) | +| Pelikan | [pelikan-io/pelikan](https://github.com/pelikan-io/pelikan) | +| Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/main/backend/core/sieve.py) | +| SkiftOS | [`src/libs/karm-base/sieve.h`](https://github.com/skift-org/skift/blob/main/src/libs/karm-base/sieve.h) | +| Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/main/src/core/compact_object.h#L124) | +| dnscrypt-proxy | [`dnscrypt-proxy/plugin_cache.go`](https://github.com/DNSCrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go) | +| encrypted-dns-server | [`src/cache.rs`](https://github.com/DNSCrypt/encrypted-dns-server/blob/master/src/cache.rs) | +| PostgREST | [JWT cache docs](https://docs.postgrest.org/en/latest/references/auth.html#jwt-cache) | +| Ceph | [`src/common/web_cache.h`](https://github.com/ceph/ceph/blob/main/src/common/web_cache.h) | + +The same source lists roughly twenty further standalone SIEVE cache libraries across Rust, Go, +Java, C#, Swift, Zig, D, Elixir, Nim, Ruby, Python, JavaScript/TypeScript and C++; see the +[full list](https://cachemon.github.io/SIEVE-website/) rather than duplicating it here. + +**Caveat:** the adopters list is maintained by the SIEVE authors. Individual entries are +verifiable through the links, but the list's completeness and currency are not independently +audited, and linked files may have changed since the entries were added. + +--- + +## 6. Checked and excluded + +Recorded so that future revisions do not re-investigate the same dead ends. + +| Candidate | Why it surfaced | Finding | Disposition | +| --- | --- | --- | --- | +| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | Excluded | +| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | Excluded | +| Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | **U** — manual check needed | +| Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | **U** — manual check needed | +| PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | Deferred to next revision | +| USENIX-hosted PDFs (SIEVE NSDI '24, 3L-Cache FAST '25) | Primary sources for evaluation details | Fetches returned HTTP 403 from this environment | Substituted with artifact repositories and program pages | + +--- + +## 7. How to update this census + +1. Bump **Census version** (semver: patch for corrections, minor for new entries, major for a + changed methodology) and set a new **Snapshot date**. +2. For every new entry, record: artifact identity, a verbatim quote showing libCacheSim use, the + source URL, the verification date, a confidence grade, and whether the adopter is independent + of the upstream project. +3. Re-fetch every source before restating it. Do not carry an unverified entry forward with a + fresh date. +4. Move anything that fails re-verification into [Section 6](#6-checked-and-excluded) with the + reason, rather than deleting it. +5. Keep Sections 3 and 5 strictly separate: simulator use versus algorithm use. +6. Add a row to the changelog below. + +Priority work for the next revision, in order of expected yield: repository-wide code search for +forks and vendored copies (limitation 1), PyPI/npm download statistics (limitation 4), manual +verification of the two Trovi artifacts, and full-text retrieval of the USENIX PDFs from an +environment that can reach usenix.org. + +--- + +## How to cite this census + +This file is versioned with the source tree; cite the census version together with the commit +that contains it. A commit permalink to `doc/adoption-census.md` is an immutable snapshot. + +```bibtex +@misc{libcachesim-adoption-census, + title = {libCacheSim Adoption Census}, + version = {1.0.0}, + howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob/develop/doc/adoption-census.md}}, + note = {Snapshot dated 2026-08-12; cite the commit permalink for an immutable version}, + year = {2026} +} +``` + +Plain-text form: + +> libCacheSim Adoption Census, version 1.0.0, snapshot 2026-08-12, +> `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim. + +--- + +## Changelog + +| Version | Date | Change | +| --- | --- | --- | +| 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From d519fe534e17f9b7a6a5c64515b8008498c555d3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:00:09 +0000 Subject: [PATCH 02/18] docs: cite census by commit permalink, not branch URL The BibTeX example used a blob/develop URL while the surrounding text told readers to cite a commit permalink. A branch moves, so the example did not identify the snapshot a reader actually consulted. The example now models the immutable form with a placeholder and gives the git command that prints the SHA. The branch URL is kept, but labeled explicitly as the read-latest link rather than the citation form. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 6bf1db85..239bd046 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -264,14 +264,23 @@ environment that can reach usenix.org. ## How to cite this census This file is versioned with the source tree; cite the census version together with the commit -that contains it. A commit permalink to `doc/adoption-census.md` is an immutable snapshot. +that contains it. **Always cite a commit permalink, never a branch URL** — a branch moves, so a +`blob/develop` link does not identify the snapshot you actually read. + +Get the SHA of the commit that last changed this file: + +```bash +git log -1 --format=%H -- doc/adoption-census.md +``` + +Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, version = {1.0.0}, - howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob/develop/doc/adoption-census.md}}, - note = {Snapshot dated 2026-08-12; cite the commit permalink for an immutable version}, + howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, + note = {Snapshot dated 2026-08-12}, year = {2026} } ``` @@ -279,7 +288,10 @@ that contains it. A commit permalink to `doc/adoption-census.md` is an immutable Plain-text form: > libCacheSim Adoption Census, version 1.0.0, snapshot 2026-08-12, -> `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim. +> `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. + +For reading rather than citing, the current version always lives at +[`doc/adoption-census.md` on `develop`](https://github.com/1a1a11a/libCacheSim/blob/develop/doc/adoption-census.md). --- From 449ffd2d706efbb92a827ae47aeab4de58a73130 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:02:43 +0000 Subject: [PATCH 03/18] docs: verify SIEVE adopter links individually, census v1.0.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review flagged that Section 5.2 promised per-entry confidence grades but carried none, and that the Pelikan row linked a repository root while the text claimed every row linked a specific implementing file. Rather than relax the claim, every one of the ten links was fetched: - 8 resolve to a primary artifact naming SIEVE and are graded A, with the quoted evidence recorded per row (immudb PR title, TiDB type declaration, Ceph/Dragonfly paper citations, PostgREST docs sentence, and the Go/Rust/Python imports) - Pelikan is downgraded to U: the upstream list links only the repo root and no specific implementing file was located - SkiftOS is downgraded to U: the linked path now returns HTTP 404 The upstream adopters list is now treated as a lead rather than as evidence, and the verification protocol says so. Also cites SCION by its arXiv abstract page and records that arXiv's stated submission date (27 Mar 2026) disagrees with the 2605 identifier prefix — the stated date is kept, since it is what the primary source says, but the discrepancy is now visible to readers rather than silently passed along. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 66 +++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 27 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 239bd046..c39c9877 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,7 +1,7 @@ # libCacheSim Adoption Census -**Census version:** 1.0.0 -**Snapshot date:** 2026-08-12 +**Census version:** 1.0.1 +**Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) A source-linked inventory of documented libCacheSim adoption. Every entry below carries a @@ -43,6 +43,10 @@ Each source URL was fetched and read on the verification date shown. Where a sou the full text was searched for `libCacheSim` / `libcachesim` before the entry was accepted. Two candidate papers surfaced by search engines were rejected this way (Section 6). +Third-party lists are not taken on trust: every per-file link in +[Section 5.2](#52-named-sieve-adopters-with-direct-source-links) was fetched individually rather +than inherited from the upstream list, which is how the two ungraded entries there were found. + ### Known limitations 1. **No GitHub-wide code search was performed.** This session's tooling was scoped to the @@ -127,8 +131,10 @@ Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. ### 3.4 SCION (PingCAP) - **Artifact:** *SCION: Size-aware Policy Orchestration for Nonstationary Object Caches*, - [arXiv:2605.01055v1](https://arxiv.org/html/2605.01055) (2026-03-27). Qizhi Wang, PingCAP - Data & AI-Innovation Lab. + [arXiv:2605.01055v1](https://arxiv.org/abs/2605.01055). Qizhi Wang, PingCAP + Data & AI-Innovation Lab. Submission history on the arXiv abstract page reads + "Fri, 27 Mar 2026"; note that this does not match the `2605` (May 2026) identifier prefix. + The date above is arXiv's own stated submission date, not an inference from the identifier. - **Evidence (quoted):** "We implement a trace-driven benchmark in C++ on top of libCacheSim." The authors additionally report integrating AdaptiveClimb/DynamicAdaptiveClimb into libCacheSim and building a trace conversion pipeline. @@ -197,31 +203,36 @@ because implementing an algorithm is not using the simulator. ### 5.2 Named SIEVE adopters with direct source links -From the SIEVE project's adopters list ([sievecache.com](https://sievecache.com/), which redirects -to [cachemon.github.io/SIEVE-website](https://cachemon.github.io/SIEVE-website/)), fetched -2026-08-12. Each entry below links to the specific implementing file or pull request, so each is -independently checkable. +Entries originate from the SIEVE project's adopters list +([sievecache.com](https://sievecache.com/), which redirects to +[cachemon.github.io/SIEVE-website](https://cachemon.github.io/SIEVE-website/)), fetched 2026-08-12. +**Every link below was then fetched individually on 2026-08-13** and graded on what that fetch +actually showed — the list itself is treated as a lead, not as evidence. -| System | Evidence link | -| --- | --- | -| immudb | [PR #1971](https://github.com/codenotary/immudb/pull/1971) | -| TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/master/pkg/infoschema/sieve.go) | -| Pelikan | [pelikan-io/pelikan](https://github.com/pelikan-io/pelikan) | -| Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/main/backend/core/sieve.py) | -| SkiftOS | [`src/libs/karm-base/sieve.h`](https://github.com/skift-org/skift/blob/main/src/libs/karm-base/sieve.h) | -| Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/main/src/core/compact_object.h#L124) | -| dnscrypt-proxy | [`dnscrypt-proxy/plugin_cache.go`](https://github.com/DNSCrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go) | -| encrypted-dns-server | [`src/cache.rs`](https://github.com/DNSCrypt/encrypted-dns-server/blob/master/src/cache.rs) | -| PostgREST | [JWT cache docs](https://docs.postgrest.org/en/latest/references/auth.html#jwt-cache) | -| Ceph | [`src/common/web_cache.h`](https://github.com/ceph/ceph/blob/main/src/common/web_cache.h) | +| System | Evidence link | What the fetch showed | Grade | +| --- | --- | --- | --- | +| immudb | [PR #1971](https://github.com/codenotary/immudb/pull/1971) | "Replace LRU with SIEVE replacement policy", merged 2024-05-17 | A | +| TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/master/pkg/infoschema/sieve.go) | `type Sieve[K comparable, V any] struct`; comment cites the SIEVE paper | A | +| Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/main/backend/core/sieve.py) | "An implementation of the SIEVE cache eviction algorithm" | A | +| Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/main/src/core/compact_object.h#L124) | `TOUCHED` hot/cold bit, comment links `nsdi24-SIEVE.pdf` | A | +| dnscrypt-proxy | [`dnscrypt-proxy/plugin_cache.go`](https://github.com/DNSCrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go) | Imports `go-sieve-cache`; uses `sievecache.NewSharded` | A | +| encrypted-dns-server | [`src/cache.rs`](https://github.com/DNSCrypt/encrypted-dns-server/blob/master/src/cache.rs) | `use sieve_cache::SieveCache` | A | +| PostgREST | [JWT cache docs](https://docs.postgrest.org/en/latest/references/auth.html#jwt-cache) | "The JWT cache is bounded and uses the SIEVE algorithm for efficient eviction." | A | +| Ceph | [`src/common/web_cache.h`](https://github.com/ceph/ceph/blob/main/src/common/web_cache.h) | "The implementation is based on SIEVE [0] with additional TTL expiration support"; cites NSDI '24 | A | +| Pelikan | [pelikan-io/pelikan](https://github.com/pelikan-io/pelikan) | Upstream list links only the repository root; no specific implementing file located | **U** | +| SkiftOS | [`src/libs/karm-base/sieve.h`](https://github.com/skift-org/skift/blob/main/src/libs/karm-base/sieve.h) | Path returns **HTTP 404** — link rot since the entry was added | **U** | + +Eight of ten resolve to a primary artifact naming SIEVE. The two graded **U** are retained as +leads: they may well be genuine adopters, but the links as published do not substantiate them. The same source lists roughly twenty further standalone SIEVE cache libraries across Rust, Go, Java, C#, Swift, Zig, D, Elixir, Nim, Ruby, Python, JavaScript/TypeScript and C++; see the -[full list](https://cachemon.github.io/SIEVE-website/) rather than duplicating it here. +[full list](https://cachemon.github.io/SIEVE-website/) rather than duplicating it here. Those +were **not** individually fetched and carry no grade in this revision. -**Caveat:** the adopters list is maintained by the SIEVE authors. Individual entries are -verifiable through the links, but the list's completeness and currency are not independently -audited, and linked files may have changed since the entries were added. +**Caveat:** the upstream adopters list is maintained by the SIEVE authors, and its completeness +is not independently audited. The 404 above shows the practical failure mode — entries are +accurate when added, then drift as the linked code moves. --- @@ -278,16 +289,16 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.0}, + version = {1.0.1}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, - note = {Snapshot dated 2026-08-12}, + note = {Snapshot dated 2026-08-13}, year = {2026} } ``` Plain-text form: -> libCacheSim Adoption Census, version 1.0.0, snapshot 2026-08-12, +> libCacheSim Adoption Census, version 1.0.1, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -299,4 +310,5 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. | | 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From 64ed72c8f9f0219cec1ad7b237f90daf9e06d63b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:03:21 +0000 Subject: [PATCH 04/18] docs: grade the Harvard SEAS aggregate claim C, not B MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review noted the row was graded B while matching the document's own definition of C: an aggregate claim with no public per-entry roster. The B grade was reasoning from editorial independence — a university news office is not the researcher's own bio page. But the rubric grades auditability, not who vouches for the claim, so the row is now C and the distinction is stated explicitly so the next revision does not re-raise it. TiDB, one of the systems the claim names, remains independently verified at Grade A in Section 5.2. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index c39c9877..a91bcbfc 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -199,7 +199,13 @@ because implementing an algorithm is not using the simulator. | Claim (quoted) | Source | Grade | | --- | --- | --- | | "S3-FIFO and SIEVE are adopted for production at Google, VMware, Redpanda, and several others, with over 60 open-source libraries and packages in 18 programming languages available on GitHub." | [junchengyang.com](https://junchengyang.com/) | C | -| "These algorithms have seen broad industry adoption — including in Android, the TiDB database, and many others — and have been implemented in dozens of open-source systems and libraries, including over 60 across more than 16 programming languages on GitHub." | [Harvard SEAS news, 2025-10-27](https://seas.harvard.edu/news/2025/10/juncheng-yang-winner-acm-award-dissertation-most-impact) | B | +| "These algorithms have seen broad industry adoption — including in Android, the TiDB database, and many others — and have been implemented in dozens of open-source systems and libraries, including over 60 across more than 16 programming languages on GitHub." | [Harvard SEAS news, 2025-10-27](https://seas.harvard.edu/news/2025/10/juncheng-yang-winner-acm-award-dissertation-most-impact) | C | + +Both are aggregate claims with no public per-entry roster, which is Grade C by this document's +rubric. A university news office is editorially independent of the researcher, but that affects +who vouches for the claim, not whether it can be audited entry by entry — so it does not lift the +grade. Note that one system named in the second claim, TiDB, is independently verified at Grade A +in Section 5.2; the aggregate figures around it are not. ### 5.2 Named SIEVE adopters with direct source links @@ -310,5 +316,5 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | -| 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. | +| 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. Downgraded the Harvard SEAS aggregate claim from B to C: editorial independence does not make an aggregate claim auditable, and the rubric grades auditability. | | 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From f092eeca6279bdbdb37c79748033962b4e995e93 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:07:43 +0000 Subject: [PATCH 05/18] docs: record link-pinning limitation, census v1.0.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review raised two issues, both correct. Section 5.1 was missing the Date checked column that the introduction promises for every entry, and that Section 4 already has. Added. The second is the more serious one: Section 5.2's evidence links point at main/master, so they can drift away from what was verified — precisely the failure this document warns about for its own citation, and exactly what already happened to the SkiftOS row (HTTP 404 on re-check). Pinning those links to commit SHAs was attempted and could not be completed from the environment that produced this snapshot: api.github.com returns 403 here, and GitHub blob pages render the commit SHA client-side, so no SHA was readable. Rather than leave the weakness unstated or fabricate revisions, it is now limitation 5, with the exact method for closing it and a note that Grade A entries in that section are verified as of a date rather than permanently reproducible. Limitations 4 and 5 are both environment-blocked rather than source-blocked, so the update protocol now points out that re-running from an unrestricted host closes three open items at once. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index a91bcbfc..817c00cd 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.1 +**Census version:** 1.0.2 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -63,6 +63,17 @@ than inherited from the upstream list, which is how the two ungraded entries the that population is not publicly enumerable. 4. **Download statistics are absent.** pypistats.org returned HTTP 429 during this snapshot; PyPI download counts should be added in the next revision. +5. **External evidence links are branch URLs, not commit permalinks.** The file-level links in + [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) point at `main`/`master`, so + they can drift away from what was verified — the same failure this document warns about for its + own citation. The SkiftOS row is that failure already realized: its linked path returned 404 on + re-check. Pinning was attempted for this snapshot and could not be completed — + `api.github.com` was unreachable (HTTP 403) from the environment that ran it, and GitHub blob + pages render the commit SHA client-side, so no SHA could be read. The next revision should pin + each link with `git ls-remote` or + `GET /repos/{owner}/{repo}/commits?path={file}&per_page=1`, rewriting + `blob/main/...` to `blob/{sha}/...`. Until then, treat Section 5.2's Grade A entries as verified + **as of 2026-08-13**, not as permanently reproducible. --- @@ -196,10 +207,10 @@ because implementing an algorithm is not using the simulator. ### 5.1 Aggregate statements -| Claim (quoted) | Source | Grade | -| --- | --- | --- | -| "S3-FIFO and SIEVE are adopted for production at Google, VMware, Redpanda, and several others, with over 60 open-source libraries and packages in 18 programming languages available on GitHub." | [junchengyang.com](https://junchengyang.com/) | C | -| "These algorithms have seen broad industry adoption — including in Android, the TiDB database, and many others — and have been implemented in dozens of open-source systems and libraries, including over 60 across more than 16 programming languages on GitHub." | [Harvard SEAS news, 2025-10-27](https://seas.harvard.edu/news/2025/10/juncheng-yang-winner-acm-award-dissertation-most-impact) | C | +| Claim (quoted) | Source | Date checked | Grade | +| --- | --- | --- | --- | +| "S3-FIFO and SIEVE are adopted for production at Google, VMware, Redpanda, and several others, with over 60 open-source libraries and packages in 18 programming languages available on GitHub." | [junchengyang.com](https://junchengyang.com/) | 2026-08-12 | C | +| "These algorithms have seen broad industry adoption — including in Android, the TiDB database, and many others — and have been implemented in dozens of open-source systems and libraries, including over 60 across more than 16 programming languages on GitHub." | [Harvard SEAS news, 2025-10-27](https://seas.harvard.edu/news/2025/10/juncheng-yang-winner-acm-award-dissertation-most-impact) | 2026-08-12 | C | Both are aggregate claims with no public per-entry roster, which is Grade C by this document's rubric. A university news office is editorially independent of the researcher, but that affects @@ -272,9 +283,14 @@ Recorded so that future revisions do not re-investigate the same dead ends. 6. Add a row to the changelog below. Priority work for the next revision, in order of expected yield: repository-wide code search for -forks and vendored copies (limitation 1), PyPI/npm download statistics (limitation 4), manual -verification of the two Trovi artifacts, and full-text retrieval of the USENIX PDFs from an -environment that can reach usenix.org. +forks and vendored copies (limitation 1), pinning Section 5.2's evidence links to commit SHAs +(limitation 5), PyPI/npm download statistics (limitation 4), manual verification of the two Trovi +artifacts, and full-text retrieval of the USENIX PDFs from an environment that can reach +usenix.org. + +Note that limitations 4 and 5 were both blocked by the *environment* the snapshot ran in, not by +the sources themselves. Re-running from a host with unrestricted access to `api.github.com`, +`pypistats.org`, and `usenix.org` would close three open items in a single pass. --- @@ -295,7 +311,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.1}, + version = {1.0.2}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -304,7 +320,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.1, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.2, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -316,5 +332,6 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | | 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. Downgraded the Harvard SEAS aggregate claim from B to C: editorial independence does not make an aggregate claim auditable, and the rubric grades auditability. | | 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From 55bb2611c10b1bdad8a7e6880530e6c2bea810d9 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:10:01 +0000 Subject: [PATCH 06/18] docs: pin evidence links to commit SHAs, census v1.0.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit documented unpinnable evidence links as a limitation after api.github.com returned 403 and blob pages proved to render SHAs client-side. git ls-remote works from here, which makes the limitation solvable rather than merely reportable. Six of the seven GitHub file links in Section 5.2 are now pinned to the commit SHA of their branch head, so each link keeps showing the revision that was actually verified. The pinned TiDB and Ceph URLs were re-fetched afterwards to confirm the quoted text is present at those exact revisions, closing the loop rather than assuming the pin is faithful. Limitation 5 now covers only what genuinely remains: the PostgREST link tracks docs.postgrest.org/en/latest/. The immudb link is a merged pull request and needs no pin. Pinning is also added to the update protocol as a standing rule, since a branch URL is not evidence — the SkiftOS 404 is what that decay looks like once it has happened. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 68 +++++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 27 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 817c00cd..d7274fdd 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.2 +**Census version:** 1.0.3 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -63,17 +63,20 @@ than inherited from the upstream list, which is how the two ungraded entries the that population is not publicly enumerable. 4. **Download statistics are absent.** pypistats.org returned HTTP 429 during this snapshot; PyPI download counts should be added in the next revision. -5. **External evidence links are branch URLs, not commit permalinks.** The file-level links in - [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) point at `main`/`master`, so - they can drift away from what was verified — the same failure this document warns about for its - own citation. The SkiftOS row is that failure already realized: its linked path returned 404 on - re-check. Pinning was attempted for this snapshot and could not be completed — - `api.github.com` was unreachable (HTTP 403) from the environment that ran it, and GitHub blob - pages render the commit SHA client-side, so no SHA could be read. The next revision should pin - each link with `git ls-remote` or - `GET /repos/{owner}/{repo}/commits?path={file}&per_page=1`, rewriting - `blob/main/...` to `blob/{sha}/...`. Until then, treat Section 5.2's Grade A entries as verified - **as of 2026-08-13**, not as permanently reproducible. +5. **Two evidence links remain unpinned.** Six of the seven GitHub file links in + [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) are pinned to commit SHAs, so + they cannot drift. Two targets could not be pinned and stay mutable: + - The **PostgREST** link points at `docs.postgrest.org/en/latest/`, which tracks the newest + release. Pin it to a versioned docs URL once the version carrying the JWT-cache text is + identified. + - The **immudb** entry links a merged pull request, whose title and merge state are already + immutable; no pin is needed. + + Pinning matters here because the drift is not hypothetical: the SkiftOS row's branch URL + returned 404 on re-check, which is how that entry lost its grade. Use + `git ls-remote https://github.com/{owner}/{repo} refs/heads/{branch}` for future entries — + `api.github.com` is unreachable (HTTP 403) from this environment and blob pages render SHAs + client-side, so `ls-remote` is the method that works here. --- @@ -226,16 +229,21 @@ Entries originate from the SIEVE project's adopters list **Every link below was then fetched individually on 2026-08-13** and graded on what that fetch actually showed — the list itself is treated as a lead, not as evidence. +GitHub file links are **pinned to commit SHAs**, not branches, so each one keeps showing the +revision that was verified. The pinned TiDB and Ceph URLs were re-fetched after pinning to confirm +the quoted text is present at those exact revisions. Two links remain unpinned for the reasons in +limitation 5. + | System | Evidence link | What the fetch showed | Grade | | --- | --- | --- | --- | | immudb | [PR #1971](https://github.com/codenotary/immudb/pull/1971) | "Replace LRU with SIEVE replacement policy", merged 2024-05-17 | A | -| TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/master/pkg/infoschema/sieve.go) | `type Sieve[K comparable, V any] struct`; comment cites the SIEVE paper | A | -| Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/main/backend/core/sieve.py) | "An implementation of the SIEVE cache eviction algorithm" | A | -| Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/main/src/core/compact_object.h#L124) | `TOUCHED` hot/cold bit, comment links `nsdi24-SIEVE.pdf` | A | -| dnscrypt-proxy | [`dnscrypt-proxy/plugin_cache.go`](https://github.com/DNSCrypt/dnscrypt-proxy/blob/master/dnscrypt-proxy/plugin_cache.go) | Imports `go-sieve-cache`; uses `sievecache.NewSharded` | A | -| encrypted-dns-server | [`src/cache.rs`](https://github.com/DNSCrypt/encrypted-dns-server/blob/master/src/cache.rs) | `use sieve_cache::SieveCache` | A | +| TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/d5f9ca5690c0a53cac36002f9d2d2bdcba25f4fc/pkg/infoschema/sieve.go) | `type Sieve[K comparable, V any] struct`; comment cites the SIEVE paper | A | +| Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/f17320128b357c1d18c7f7b889a3f3d2b3115120/backend/core/sieve.py) | "An implementation of the SIEVE cache eviction algorithm" | A | +| Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/f4019d7fec0ddcd1e6484dd6eeade7d52b146af6/src/core/compact_object.h#L124) | `TOUCHED` hot/cold bit, comment links `nsdi24-SIEVE.pdf` | A | +| dnscrypt-proxy | [`dnscrypt-proxy/plugin_cache.go`](https://github.com/DNSCrypt/dnscrypt-proxy/blob/1a3ace9ac88461f76e1e66d1270ae645cbe2993b/dnscrypt-proxy/plugin_cache.go) | Imports `go-sieve-cache`; uses `sievecache.NewSharded` | A | +| encrypted-dns-server | [`src/cache.rs`](https://github.com/DNSCrypt/encrypted-dns-server/blob/3754243bf96db5873ab49b58c057f00ef3a16a52/src/cache.rs) | `use sieve_cache::SieveCache` | A | | PostgREST | [JWT cache docs](https://docs.postgrest.org/en/latest/references/auth.html#jwt-cache) | "The JWT cache is bounded and uses the SIEVE algorithm for efficient eviction." | A | -| Ceph | [`src/common/web_cache.h`](https://github.com/ceph/ceph/blob/main/src/common/web_cache.h) | "The implementation is based on SIEVE [0] with additional TTL expiration support"; cites NSDI '24 | A | +| Ceph | [`src/common/web_cache.h`](https://github.com/ceph/ceph/blob/5995d21863b3992bd9f463b5a0f774869351be36/src/common/web_cache.h) | "The implementation is based on SIEVE [0] with additional TTL expiration support"; cites NSDI '24 | A | | Pelikan | [pelikan-io/pelikan](https://github.com/pelikan-io/pelikan) | Upstream list links only the repository root; no specific implementing file located | **U** | | SkiftOS | [`src/libs/karm-base/sieve.h`](https://github.com/skift-org/skift/blob/main/src/libs/karm-base/sieve.h) | Path returns **HTTP 404** — link rot since the entry was added | **U** | @@ -282,15 +290,20 @@ Recorded so that future revisions do not re-investigate the same dead ends. 5. Keep Sections 3 and 5 strictly separate: simulator use versus algorithm use. 6. Add a row to the changelog below. +Pin every new GitHub evidence link at the time you add it — +`git ls-remote https://github.com/{owner}/{repo} refs/heads/{branch}` — and re-fetch the pinned +URL to confirm the quoted text is present at that revision. A branch URL is not evidence; it is a +promise that decays. + Priority work for the next revision, in order of expected yield: repository-wide code search for -forks and vendored copies (limitation 1), pinning Section 5.2's evidence links to commit SHAs -(limitation 5), PyPI/npm download statistics (limitation 4), manual verification of the two Trovi -artifacts, and full-text retrieval of the USENIX PDFs from an environment that can reach -usenix.org. +forks and vendored copies (limitation 1), PyPI/npm download statistics (limitation 4), manual +verification of the two Trovi artifacts, full-text retrieval of the USENIX PDFs from an +environment that can reach usenix.org, and pinning the PostgREST docs link to a versioned URL +(limitation 5). -Note that limitations 4 and 5 were both blocked by the *environment* the snapshot ran in, not by -the sources themselves. Re-running from a host with unrestricted access to `api.github.com`, -`pypistats.org`, and `usenix.org` would close three open items in a single pass. +Limitations 1 and 4 are blocked by the *environment* a snapshot runs in, not by the sources. +Re-running from a host with repository-search access and unrestricted reach to `pypistats.org` +and `usenix.org` closes several open items in a single pass. --- @@ -311,7 +324,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.2}, + version = {1.0.3}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -320,7 +333,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.2, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.3, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -332,6 +345,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | | 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | | 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. Downgraded the Harvard SEAS aggregate claim from B to C: editorial independence does not make an aggregate claim auditable, and the rubric grades auditability. | | 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From 34a995cec182491f8f53da8476fffad1bdc5b746 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:13:33 +0000 Subject: [PATCH 07/18] docs: date the excluded candidates, census v1.0.4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Section 6 was the last table with neither a Date checked column nor a surrounding statement giving one, so the introduction's promise that every entry records when its evidence was checked did not hold there. Added the column. Also noted why dates matter most in this section specifically: an excluded candidate is only trustworthy as of its last check, and a paper that did not mention libCacheSim in one snapshot may cite it in a later version — so a stale exclusion is worse than no exclusion. Coverage is now complete. Sections 2, 3 and 5.2 carry their verification date in the sentence introducing each table; Sections 4, 5.1 and 6 carry a per-row column. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index d7274fdd..cfacb6d1 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.3 +**Census version:** 1.0.4 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -263,16 +263,18 @@ accurate when added, then drift as the linked code moves. ## 6. Checked and excluded -Recorded so that future revisions do not re-investigate the same dead ends. +Recorded so that future revisions do not re-investigate the same dead ends. The `Date checked` +column matters most here: a dead end is only worth trusting as recently as its last check, and a +paper that did not mention libCacheSim in one snapshot may cite it in a later version. -| Candidate | Why it surfaced | Finding | Disposition | -| --- | --- | --- | --- | -| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | Excluded | -| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | Excluded | -| Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | **U** — manual check needed | -| Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | **U** — manual check needed | -| PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | Deferred to next revision | -| USENIX-hosted PDFs (SIEVE NSDI '24, 3L-Cache FAST '25) | Primary sources for evaluation details | Fetches returned HTTP 403 from this environment | Substituted with artifact repositories and program pages | +| Candidate | Why it surfaced | Finding | Date checked | Disposition | +| --- | --- | --- | --- | --- | +| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | 2026-08-12 | Excluded | +| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | 2026-08-12 | Excluded | +| Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | 2026-08-12 | **U** — manual check needed | +| Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | 2026-08-12 | **U** — manual check needed | +| PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | 2026-08-12 | Deferred to next revision | +| USENIX-hosted PDFs (SIEVE NSDI '24, 3L-Cache FAST '25) | Primary sources for evaluation details | Fetches returned HTTP 403 from this environment | 2026-08-12 | Substituted with artifact repositories and program pages | --- @@ -324,7 +326,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.3}, + version = {1.0.4}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -333,7 +335,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.3, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.4, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -345,6 +347,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.4 | 2026-08-13 | Added the missing `Date checked` column to Section 6, completing the coverage the introduction promises: every table in the document now records when its evidence was last checked. Noted why that column matters most for excluded candidates — a dead end is only trustworthy as of its last check, and a paper may cite libCacheSim in a later version. | | 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | | 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | | 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. Downgraded the Harvard SEAS aggregate claim from B to C: editorial independence does not make an aggregate claim auditable, and the rubric grades auditability. | From 2f20988f1644f597d8395e24fda937f913844359 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:17:57 +0000 Subject: [PATCH 08/18] docs: cite code not pull requests, census v1.0.5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review pointed out that a merged pull request is not an immutable citation: GitHub titles stay editable after merge, so the immudb row's quoted evidence could silently change. That is correct, and it also invalidated the previous commit's claim that the PR link needed no pin. The immudb row now cites embedded/cache/cache.go pinned at 1a5f54e, verified at that revision to read "Cache implements the SIEVE cache replacement policy" with a hand pointer and per-entry visited flags — stronger evidence than the PR title anyway, since it shows the algorithm rather than a description of a change to it. Applying the same reasoning elsewhere: the 3L-Cache entry quotes README text through a repository-root link, which is mutable for the same reason, so it is now pinned at 134cd15. The quote is corrected to match that revision verbatim ("3L Cache", unhyphenated there). Section 5.2 now has no unpinned GitHub links. Only the PostgREST docs URL remains mutable, and limitation 5 records why. The update protocol gains the rule that follows from all this: cite the code, not the pull request. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 49 ++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index cfacb6d1..9ab94d9a 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.4 +**Census version:** 1.0.5 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -63,20 +63,20 @@ than inherited from the upstream list, which is how the two ungraded entries the that population is not publicly enumerable. 4. **Download statistics are absent.** pypistats.org returned HTTP 429 during this snapshot; PyPI download counts should be added in the next revision. -5. **Two evidence links remain unpinned.** Six of the seven GitHub file links in - [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) are pinned to commit SHAs, so - they cannot drift. Two targets could not be pinned and stay mutable: - - The **PostgREST** link points at `docs.postgrest.org/en/latest/`, which tracks the newest - release. Pin it to a versioned docs URL once the version carrying the JWT-cache text is - identified. - - The **immudb** entry links a merged pull request, whose title and merge state are already - immutable; no pin is needed. +5. **One evidence link remains unpinned.** Every GitHub link in + [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) is pinned to a commit SHA, so + none of them can drift. The exception is **PostgREST**, whose link points at + `docs.postgrest.org/en/latest/` and therefore tracks the newest release; pin it to a versioned + docs URL once the version carrying the JWT-cache text is identified. Pinning matters here because the drift is not hypothetical: the SkiftOS row's branch URL - returned 404 on re-check, which is how that entry lost its grade. Use - `git ls-remote https://github.com/{owner}/{repo} refs/heads/{branch}` for future entries — - `api.github.com` is unreachable (HTTP 403) from this environment and blob pages render SHAs - client-side, so `ls-remote` is the method that works here. + returned 404 on re-check, which is how that entry lost its grade. Note also that a merged pull + request is **not** an immutable citation — GitHub titles stay editable after merge, so evidence + quoted from a PR title can silently change. Cite the code, not the pull request. Use + `git ls-remote https://github.com/{owner}/{repo} refs/heads/{branch}` (or + `refs/pull/{n}/head` for a specific PR revision) — `api.github.com` is unreachable (HTTP 403) + from this environment and blob pages render SHAs client-side, so `ls-remote` is the method + that works here. --- @@ -119,10 +119,12 @@ Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. - **Artifact:** *3L-Cache: Low Overhead and Precise Learning-based Eviction Policy for Caches*, USENIX FAST '25 ([program page](https://www.usenix.org/conference/fast25/presentation/zhou-wenbin)). - Artifact repository: [github.com/optiq-lab/3L-Cache](https://github.com/optiq-lab/3L-Cache). -- **Evidence (quoted):** "3L-Cache is implemented in the libCacheSim library, and its experimental + Artifact repository: [github.com/optiq-lab/3L-Cache](https://github.com/optiq-lab/3L-Cache), + pinned at [`134cd15`](https://github.com/optiq-lab/3L-Cache/blob/134cd159b635cdab75419a4281bed1a330fef31f/README.md). +- **Evidence (quoted):** "3L Cache is implemented in the libCacheSim library, and its experimental environment configuration is consistent with libCacheSim." The repository layout is annotated - "3L-Cache/ -- Forked from LibCacheSim, which is a platform for cache evaluation." + "3L-Cache/ -- Forked from LibCacheSim, which is a platform for cache evaluation." (Quoted from + the pinned README revision; the project spells its name both with and without the hyphen.) - **Use:** Whole-project fork of libCacheSim used as the evaluation platform (reported 4855 traces, twelve comparison policies). - **Upstreamed:** tracked in [issue #119](https://github.com/1a1a11a/libCacheSim/issues/119) @@ -229,14 +231,14 @@ Entries originate from the SIEVE project's adopters list **Every link below was then fetched individually on 2026-08-13** and graded on what that fetch actually showed — the list itself is treated as a lead, not as evidence. -GitHub file links are **pinned to commit SHAs**, not branches, so each one keeps showing the -revision that was verified. The pinned TiDB and Ceph URLs were re-fetched after pinning to confirm -the quoted text is present at those exact revisions. Two links remain unpinned for the reasons in -limitation 5. +GitHub links are **pinned to commit SHAs**, not branches or pull requests, so each one keeps +showing the revision that was verified. The pinned TiDB, Ceph and immudb URLs were re-fetched +after pinning to confirm the quoted text is present at those exact revisions. Only the PostgREST +link remains unpinned, for the reason in limitation 5. | System | Evidence link | What the fetch showed | Grade | | --- | --- | --- | --- | -| immudb | [PR #1971](https://github.com/codenotary/immudb/pull/1971) | "Replace LRU with SIEVE replacement policy", merged 2024-05-17 | A | +| immudb | [`embedded/cache/cache.go`](https://github.com/codenotary/immudb/blob/1a5f54e83219b2e1a3d6810ca2f879cb2163c714/embedded/cache/cache.go) | "Cache implements the SIEVE cache replacement policy"; `hand` pointer and per-entry `visited` flags | A | | TiDB | [`pkg/infoschema/sieve.go`](https://github.com/pingcap/tidb/blob/d5f9ca5690c0a53cac36002f9d2d2bdcba25f4fc/pkg/infoschema/sieve.go) | `type Sieve[K comparable, V any] struct`; comment cites the SIEVE paper | A | | Nyrkiö | [`backend/core/sieve.py`](https://github.com/nyrkio/nyrkio/blob/f17320128b357c1d18c7f7b889a3f3d2b3115120/backend/core/sieve.py) | "An implementation of the SIEVE cache eviction algorithm" | A | | Dragonfly | [`src/core/compact_object.h`](https://github.com/dragonflydb/dragonfly/blob/f4019d7fec0ddcd1e6484dd6eeade7d52b146af6/src/core/compact_object.h#L124) | `TOUCHED` hot/cold bit, comment links `nsdi24-SIEVE.pdf` | A | @@ -326,7 +328,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.4}, + version = {1.0.5}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -335,7 +337,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.4, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.5, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -347,6 +349,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link in Section 5.2 is now pinned; only the PostgREST docs URL remains mutable. | | 1.0.4 | 2026-08-13 | Added the missing `Date checked` column to Section 6, completing the coverage the introduction promises: every table in the document now records when its evidence was last checked. Noted why that column matters most for excluded candidates — a dead end is only trustworthy as of its last check, and a paper may cite libCacheSim in a later version. | | 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | | 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | From f1ef04c55fad24d6ba559592d6f972bd39e2e074 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:21:27 +0000 Subject: [PATCH 09/18] docs: grade the claimed relationship, census v1.0.6 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review findings, the first structural. Grade A was defined as evidence stating "use of libCacheSim unambiguously", but Section 5.2 assigns A to projects the document explicitly says are not libCacheSim users. A reader applying the rubric literally would read those grades as confirming exactly the relationship Section 1 forbids conflating — the rubric contradicted the document's central rule. Grades are now defined against the relationship each section claims, with the split stated: Sections 2-4 claim use of libCacheSim, Section 5 claims adoption of an algorithm designed in it. Section 5.2 repeats the point at the table, so a reader landing there does not need to have read Section 1. Second, limitation 5 claimed every GitHub link in Section 5.2 was pinned. Two are not: Pelikan links a repository root because no implementing file exists to pin, and SkiftOS keeps its branch URL because reproducing the 404 is the evidence for its grade. Pinning either would misrepresent them. The claim is now scoped to the Grade A GitHub links it actually covers, and each exception says why it is exempt rather than pending. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 48 +++++++++++++++++++++++++++++------------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 9ab94d9a..67024617 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.5 +**Census version:** 1.0.6 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -32,10 +32,18 @@ an order of magnitude, and the distinction is the single most important integrit | Grade | Meaning | | --- | --- | -| **A** | Primary source, quoted verbatim, states use of libCacheSim unambiguously. | -| **B** | Primary source confirms the relationship, but the extent of use is inferred. | +| **A** | Primary source, quoted verbatim, establishes the relationship claimed by that section unambiguously. | +| **B** | Primary source confirms the relationship, but its extent is inferred. | | **C** | Self-reported or aggregate claim with no public per-entry roster to audit. | -| **U** | Lead identified but not verifiable by automated fetch; retained for manual follow-up. | +| **U** | Lead identified, but the cited source does not substantiate it; retained for manual follow-up. | + +**A grade measures evidence strength for the relationship its own section claims — never for +libCacheSim adoption in general.** The two relationships differ by section: + +- Sections 2–4 claim **use of libCacheSim**, so a grade there speaks to that. +- Section 5 claims **adoption of an algorithm designed in libCacheSim**, so an A there certifies + a SIEVE implementation and says nothing about whether that project uses libCacheSim. Reading a + Section 5.2 A as libCacheSim adoption would commit exactly the conflation the rule above forbids. ### Verification protocol @@ -63,11 +71,16 @@ than inherited from the upstream list, which is how the two ungraded entries the that population is not publicly enumerable. 4. **Download statistics are absent.** pypistats.org returned HTTP 429 during this snapshot; PyPI download counts should be added in the next revision. -5. **One evidence link remains unpinned.** Every GitHub link in - [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) is pinned to a commit SHA, so - none of them can drift. The exception is **PostgREST**, whose link points at - `docs.postgrest.org/en/latest/` and therefore tracks the newest release; pin it to a versioned - docs URL once the version carrying the JWT-cache text is identified. +5. **Three links are unpinned, one of them fixable.** Every **GitHub** link backing a **Grade A** + entry in [Section 5.2](#52-named-sieve-adopters-with-direct-source-links) is pinned to a commit + SHA and cannot drift. The exceptions: + - **PostgREST** (Grade A) — not a GitHub link; it points at `docs.postgrest.org/en/latest/`, + which tracks the newest release. Pin it to a versioned docs URL once the version carrying the + JWT-cache text is identified. **This is the one worth fixing.** + - **Pelikan** (Grade U) — links a repository root because no implementing file was located, so + there is nothing specific to pin. Pinning the root would manufacture false precision. + - **SkiftOS** (Grade U) — deliberately keeps its `blob/main` URL, because reproducing the + **404 is the evidence** for its grade. A pinned SHA would hide the link rot being documented. Pinning matters here because the drift is not hypothetical: the SkiftOS row's branch URL returned 404 on re-check, which is how that entry lost its grade. Note also that a merged pull @@ -231,10 +244,14 @@ Entries originate from the SIEVE project's adopters list **Every link below was then fetched individually on 2026-08-13** and graded on what that fetch actually showed — the list itself is treated as a lead, not as evidence. -GitHub links are **pinned to commit SHAs**, not branches or pull requests, so each one keeps -showing the revision that was verified. The pinned TiDB, Ceph and immudb URLs were re-fetched -after pinning to confirm the quoted text is present at those exact revisions. Only the PostgREST -link remains unpinned, for the reason in limitation 5. +Every GitHub link backing a **Grade A** row below is **pinned to a commit SHA**, not a branch or a +pull request, so each keeps showing the revision that was verified; the pinned TiDB, Ceph and +immudb URLs were re-fetched after pinning to confirm the quoted text is present at those exact +revisions. The **Grade U** rows are intentionally left unpinned — see limitation 5 — as is the +PostgREST row, which points at a docs site rather than a repository. + +Grades in this table certify a **SIEVE implementation**, not libCacheSim use; see +[Confidence grades](#confidence-grades). | System | Evidence link | What the fetch showed | Grade | | --- | --- | --- | --- | @@ -328,7 +345,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.5}, + version = {1.0.6}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -337,7 +354,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.5, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.6, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -349,6 +366,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.6 | 2026-08-13 | Redefined the grade rubric in terms of *the relationship each section claims* rather than "use of libCacheSim". The old wording made a Section 5.2 Grade A read as certifying libCacheSim adoption, which is the exact conflation Section 1 forbids; grades there certify a SIEVE implementation and nothing more. Also scoped the pinning claim to the Grade A GitHub links it actually covers — the two Grade U rows are unpinned on purpose, and SkiftOS keeps a branch URL because reproducing its 404 is the evidence. | | 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link in Section 5.2 is now pinned; only the PostgREST docs URL remains mutable. | | 1.0.4 | 2026-08-13 | Added the missing `Date checked` column to Section 6, completing the coverage the introduction promises: every table in the document now records when its evidence was last checked. Noted why that column matters most for excluded candidates — a dead end is only trustworthy as of its last check, and a paper may cite libCacheSim in a later version. | | 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | From 2d1dba6d14d660cc587bb8346abc8bb42786b5e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:25:28 +0000 Subject: [PATCH 10/18] docs: scope grades per section, census v1.0.7 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two follow-on defects from the 1.0.6 rubric change, both correct. Section 2 was grouped with 3-4 as claiming "use of libCacheSim", but stars, package releases and dependency-graph counts are distribution signals — availability, not usage. Grouping them re-created the category inflation the rubric exists to prevent, one layer up. Section 2 now has its own claim: the value was measured as stated on the date given. The section header says the same thing, so a reader skimming the table is not misled by the A column. Added the corollary the reviewer's point implies: grades are not comparable across sections, and counting every A in the document as an adopter would inflate the census with star counts and SIEVE ports. The update checklist had the same shape of bug: it required a quote showing libCacheSim use and an independence assessment for every new entry, which a legitimate Section 5 algorithm adopter cannot supply without contradicting rule 5. The required quote is now the one establishing the relationship the target section claims, and independence is recorded for Section 3 entries only, where it actually distinguishes third-party validation from the project's own work. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 67024617..687e704b 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.6 +**Census version:** 1.0.7 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -38,12 +38,20 @@ an order of magnitude, and the distinction is the single most important integrit | **U** | Lead identified, but the cited source does not substantiate it; retained for manual follow-up. | **A grade measures evidence strength for the relationship its own section claims — never for -libCacheSim adoption in general.** The two relationships differ by section: +libCacheSim adoption in general.** Each section claims something different: -- Sections 2–4 claim **use of libCacheSim**, so a grade there speaks to that. -- Section 5 claims **adoption of an algorithm designed in libCacheSim**, so an A there certifies - a SIEVE implementation and says nothing about whether that project uses libCacheSim. Reading a - Section 5.2 A as libCacheSim adoption would commit exactly the conflation the rule above forbids. +- **Section 2** claims only that a **published fact was measured as stated** on the date given. + Stars, package releases and dependency counts describe how libCacheSim is *distributed*; none of + them shows that anyone uses it. An A there means the number was read correctly, nothing more. +- **Sections 3–4** claim **use of libCacheSim**, so a grade there speaks to that. +- **Section 5** claims **adoption of an algorithm designed in libCacheSim**, so an A there + certifies a SIEVE implementation and says nothing about whether that project uses libCacheSim. + Reading a Section 5.2 A as libCacheSim adoption would commit exactly the conflation the rule + above forbids. + +Grades are therefore not comparable across sections. Counting every A in this document as an +adopter would inflate the census with star counts and SIEVE ports — the failure this rubric exists +to prevent. ### Verification protocol @@ -95,7 +103,12 @@ than inherited from the upstream list, which is how the two ungraded entries the ## 2. Distribution and repository signals -Measured facts about how libCacheSim is published and consumed. All figures fetched 2026-08-12. +Measured facts about how libCacheSim is **published**. All figures fetched 2026-08-12. + +These are distribution signals, not adoption evidence: a star, a package release, or the existence +of a binding repository shows availability, not that anyone runs the simulator. A Grade A here +certifies that the value was read correctly on the date shown — see +[Confidence grades](#confidence-grades). | Signal | Value | Source | Grade | | --- | --- | --- | --- | @@ -301,9 +314,13 @@ paper that did not mention libCacheSim in one snapshot may cite it in a later ve 1. Bump **Census version** (semver: patch for corrections, minor for new entries, major for a changed methodology) and set a new **Snapshot date**. -2. For every new entry, record: artifact identity, a verbatim quote showing libCacheSim use, the - source URL, the verification date, a confidence grade, and whether the adopter is independent - of the upstream project. +2. For every new entry, record: artifact identity, the source URL, the verification date, a + confidence grade, and **a verbatim quote establishing the relationship its section claims** — + libCacheSim use for Sections 3–4, an algorithm implementation for Section 5, the measured value + for Section 2. Do not demand a libCacheSim-use quote from a Section 5 entry; an algorithm + adopter need not be a libCacheSim user, and requiring one would force the conflation rule 5 + forbids. Record upstream independence for **Section 3 entries only** — it is what distinguishes + third-party validation from the project's own work, and it is meaningless for the others. 3. Re-fetch every source before restating it. Do not carry an unverified entry forward with a fresh date. 4. Move anything that fails re-verification into [Section 6](#6-checked-and-excluded) with the @@ -345,7 +362,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.6}, + version = {1.0.7}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -354,7 +371,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.6, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.7, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -366,6 +383,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.7 | 2026-08-13 | Split Section 2 out of the "claims use of libCacheSim" grouping introduced in 1.0.6: stars, package releases and dependency counts are distribution signals, so an A there certifies only that the value was read correctly. Added that grades are not comparable across sections. Parameterized the update checklist by target section — a Section 5 entry cannot supply a libCacheSim-use quote without committing the conflation the rules forbid, and upstream independence is now recorded for Section 3 only. | | 1.0.6 | 2026-08-13 | Redefined the grade rubric in terms of *the relationship each section claims* rather than "use of libCacheSim". The old wording made a Section 5.2 Grade A read as certifying libCacheSim adoption, which is the exact conflation Section 1 forbids; grades there certify a SIEVE implementation and nothing more. Also scoped the pinning claim to the Grade A GitHub links it actually covers — the two Grade U rows are unpinned on purpose, and SkiftOS keeps a branch URL because reproducing its 404 is the evidence. | | 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link in Section 5.2 is now pinned; only the PostgREST docs URL remains mutable. | | 1.0.4 | 2026-08-13 | Added the missing `Date checked` column to Section 6, completing the coverage the introduction promises: every table in the document now records when its evidence was last checked. Noted why that column matters most for excluded candidates — a dead end is only trustworthy as of its last check, and a paper may cite libCacheSim in a later version. | From 795ff8c077de430862a472c0a53b5d89ddb295df Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:30:36 +0000 Subject: [PATCH 11/18] docs: give Section 6 dispositions, census v1.0.8 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two findings, both correct. The header promised a confidence grade for every entry, but Section 6 has no grade column: four rows read only "Excluded", "Deferred" or "Substituted", and two embedded a bare U in the disposition. Rather than bolt grades onto refuted candidates — which would imply they belong in the census — Section 6 is now explicitly exempt and carries a defined disposition vocabulary instead: Excluded checked and refuted; the source does not support the claim Unverified could not be checked; neither confirmed nor refuted Deferred blocked by the snapshot environment, not by the source Substituted primary unreachable; an equivalent source was used The two Trovi rows move from a bare U to Unverified, so grade letters and disposition words are no longer mixed in one column. Second, the v1.0.0 changelog said six distribution signals where Section 2 has seven rows: stars, forks, PyPI package, PyPI maintainers, npm package, Python binding repository, dependency-graph dependents. Counted and corrected. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 44 ++++++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 687e704b..74ef11ae 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,14 +1,17 @@ # libCacheSim Adoption Census -**Census version:** 1.0.7 +**Census version:** 1.0.8 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) -A source-linked inventory of documented libCacheSim adoption. Every entry below carries a -public URL, the quoted evidence that supports it, the date the evidence was checked, and a -confidence grade. Entries that could not be verified are recorded as such rather than dropped -silently, and claims that were checked and found to be false are listed in -[Checked and excluded](#6-checked-and-excluded). +A source-linked inventory of documented libCacheSim adoption. Every entry in +**Sections 2–5** carries a public URL, the quoted evidence that supports it, the date the evidence +was checked, and a confidence grade. + +**Section 6 is different by design.** It holds candidates that were investigated and *rejected*, +so it records a **disposition** instead of a grade — grading a paper that turned out not to +mention libCacheSim would imply it belongs in the census. Rejected candidates are kept rather than +deleted, so a later revision does not re-investigate them. This document is versioned with the source tree, so any commit of this file is a citable snapshot. See [How to cite this census](#how-to-cite-this-census). @@ -299,14 +302,24 @@ Recorded so that future revisions do not re-investigate the same dead ends. The column matters most here: a dead end is only worth trusting as recently as its last check, and a paper that did not mention libCacheSim in one snapshot may cite it in a later version. +These rows carry a **disposition**, not a confidence grade — the A/B/C/U rubric measures how well +a source supports an entry that belongs in the census, and nothing here does. The vocabulary: + +| Disposition | Meaning | +| --- | --- | +| **Excluded** | Checked and refuted: the source does not support the claim. Re-check only if the source is revised. | +| **Unverified** | Could not be checked at all. Neither confirmed nor refuted; retained as a lead. | +| **Deferred** | Blocked by the environment the snapshot ran in, not by the source. Retry from a host without that restriction. | +| **Substituted** | Primary source unreachable; an equivalent source was used and the entry lives in the census proper. | + | Candidate | Why it surfaced | Finding | Date checked | Disposition | | --- | --- | --- | --- | --- | -| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | 2026-08-12 | Excluded | -| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | 2026-08-12 | Excluded | -| Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | 2026-08-12 | **U** — manual check needed | -| Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | 2026-08-12 | **U** — manual check needed | -| PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | 2026-08-12 | Deferred to next revision | -| USENIX-hosted PDFs (SIEVE NSDI '24, 3L-Cache FAST '25) | Primary sources for evaluation details | Fetches returned HTTP 403 from this environment | 2026-08-12 | Substituted with artifact repositories and program pages | +| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | 2026-08-12 | **Excluded** | +| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | 2026-08-12 | **Excluded** | +| Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | 2026-08-12 | **Unverified** | +| Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | 2026-08-12 | **Unverified** | +| PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | 2026-08-12 | **Deferred** | +| USENIX-hosted PDFs (SIEVE NSDI '24, 3L-Cache FAST '25) | Primary sources for evaluation details | Fetches returned HTTP 403 from this environment | 2026-08-12 | **Substituted** — artifact repositories and program pages used instead | --- @@ -362,7 +375,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.7}, + version = {1.0.8}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -371,7 +384,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.7, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.8, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -383,6 +396,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.8 | 2026-08-13 | Exempted Section 6 from the grading promise and gave it a defined disposition vocabulary (Excluded / Unverified / Deferred / Substituted) — grading a refuted candidate would imply it belongs in the census, and four rows carried no grade at all. Corrected the v1.0.0 changelog entry: Section 2 has seven distribution signals, not six. | | 1.0.7 | 2026-08-13 | Split Section 2 out of the "claims use of libCacheSim" grouping introduced in 1.0.6: stars, package releases and dependency counts are distribution signals, so an A there certifies only that the value was read correctly. Added that grades are not comparable across sections. Parameterized the update checklist by target section — a Section 5 entry cannot supply a libCacheSim-use quote without committing the conflation the rules forbid, and upstream independence is now recorded for Section 3 only. | | 1.0.6 | 2026-08-13 | Redefined the grade rubric in terms of *the relationship each section claims* rather than "use of libCacheSim". The old wording made a Section 5.2 Grade A read as certifying libCacheSim adoption, which is the exact conflation Section 1 forbids; grades there certify a SIEVE implementation and nothing more. Also scoped the pinning claim to the Grade A GitHub links it actually covers — the two Grade U rows are unpinned on purpose, and SkiftOS keeps a branch URL because reproducing its 404 is the evidence. | | 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link in Section 5.2 is now pinned; only the PostgREST docs URL remains mutable. | @@ -390,4 +404,4 @@ For reading rather than citing, the current version always lives at | 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | | 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | | 1.0.1 | 2026-08-13 | Individually fetched all ten Section 5.2 adopter links instead of inheriting them: 8 graded A against primary artifacts, Pelikan and SkiftOS downgraded to U (repo-root-only link; HTTP 404 link rot). Added grades to Section 5.2 so every entry carries one, as the introduction promises. Cited SCION by its arXiv abstract page and flagged that arXiv's stated submission date disagrees with its identifier prefix. Citation example now uses a commit permalink rather than a branch URL. Downgraded the Harvard SEAS aggregate claim from B to C: editorial independence does not make an aggregate claim auditable, and the rubric grades auditability. | -| 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 6 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | +| 1.0.0 | 2026-08-12 | Initial census: 5 confirmed direct users, 7 distribution signals, 2 self-reported aggregate claims, 10 named algorithm-lineage adopters, 6 excluded or deferred candidates. | From a1fc7bd7f439d19b32dd94e8579f3007aeb12252 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:34:02 +0000 Subject: [PATCH 12/18] docs: distinguish settled from open candidates, census v1.0.9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings from the same review, all consequences of the 1.0.8 disposition change. Section 6 was described as candidates "investigated and rejected" whose entries need not be re-investigated. That is true only of the Excluded rows. The Unverified Trovi leads and the Deferred download statistics are open work that the next-revision priority list explicitly calls for, and the old wording invited a maintainer to skip them. The header now says checked-but-not-admitted, marks only Excluded as settled, and links Unverified and Deferred to the priorities. The header also promised "quoted evidence" for every entry in Sections 2-5, but Section 2 rows are measured values — a star count is a number to read, not a sentence to quote. The promise now names what each section actually carries, and the update checklist matches instead of asking for a verbatim quote of a number. The README carried the same unscoped grade promise; it now mentions that checked-but-unqualified candidates are kept separately with a disposition. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- README.md | 5 +++-- doc/adoption-census.md | 31 ++++++++++++++++++------------- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 46fe857c..6247249d 100644 --- a/README.md +++ b/README.md @@ -383,8 +383,9 @@ We provide a more comprehensive cache datasets at [https://github.com/cacheMon/c ## Who uses libCacheSim See the [adoption census](/doc/adoption-census.md) for a source-linked inventory of documented libCacheSim adoption — research artifacts built on it, distribution channels, and downstream -adoption of algorithms designed in it. Every entry carries its evidence, source URL, verification -date, and confidence grade. +adoption of algorithms designed in it. Every census entry carries its evidence, source URL, +verification date, and confidence grade; candidates that were checked but did not qualify are kept +in a separate section with a disposition instead, so they are not silently dropped. --- ## Contributions diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 74ef11ae..88b99d1f 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,17 +1,20 @@ # libCacheSim Adoption Census -**Census version:** 1.0.8 +**Census version:** 1.0.9 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) -A source-linked inventory of documented libCacheSim adoption. Every entry in -**Sections 2–5** carries a public URL, the quoted evidence that supports it, the date the evidence -was checked, and a confidence grade. +A source-linked inventory of documented libCacheSim adoption. Every entry in **Sections 2–5** +carries a public URL, the date the evidence was checked, a confidence grade, and the evidence +itself — a **verbatim quote** in Sections 3–5, and in Section 2 the **measured value**, since a +star count or release date is a number to read rather than a sentence to quote. -**Section 6 is different by design.** It holds candidates that were investigated and *rejected*, -so it records a **disposition** instead of a grade — grading a paper that turned out not to -mention libCacheSim would imply it belongs in the census. Rejected candidates are kept rather than -deleted, so a later revision does not re-investigate them. +**Section 6 is different by design.** It holds candidates that were checked but did not enter the +census, and records a **disposition** rather than a grade — grading a paper that turned out not to +mention libCacheSim would imply it belongs here. Only the **Excluded** rows are settled; the +**Unverified** and **Deferred** rows are open follow-up work, and appear in the +[next-revision priorities](#7-how-to-update-this-census). Nothing in the section is deleted, so a +later revision can tell a refuted candidate from one that was never checked. This document is versioned with the source tree, so any commit of this file is a citable snapshot. See [How to cite this census](#how-to-cite-this-census). @@ -328,9 +331,10 @@ a source supports an entry that belongs in the census, and nothing here does. Th 1. Bump **Census version** (semver: patch for corrections, minor for new entries, major for a changed methodology) and set a new **Snapshot date**. 2. For every new entry, record: artifact identity, the source URL, the verification date, a - confidence grade, and **a verbatim quote establishing the relationship its section claims** — - libCacheSim use for Sections 3–4, an algorithm implementation for Section 5, the measured value - for Section 2. Do not demand a libCacheSim-use quote from a Section 5 entry; an algorithm + confidence grade, and evidence for **the relationship its section claims** — a verbatim quote + showing libCacheSim use for Sections 3–4, a verbatim quote showing an algorithm implementation + for Section 5, and for Section 2 the measured value with the page it was read from (there is no + sentence to quote). Do not demand a libCacheSim-use quote from a Section 5 entry; an algorithm adopter need not be a libCacheSim user, and requiring one would force the conflation rule 5 forbids. Record upstream independence for **Section 3 entries only** — it is what distinguishes third-party validation from the project's own work, and it is meaningless for the others. @@ -375,7 +379,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.8}, + version = {1.0.9}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -384,7 +388,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.8, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.9, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -396,6 +400,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.9 | 2026-08-13 | Stopped describing all of Section 6 as rejected: only the Excluded rows are settled, while Unverified and Deferred rows are open follow-up work and now point at the next-revision priorities, so a maintainer does not skip them. Narrowed the evidence promise — Section 2 records a measured value, not a verbatim quote, since a star count is a number to read rather than a sentence to quote; the update checklist says the same. Scoped the README's grade promise to match. | | 1.0.8 | 2026-08-13 | Exempted Section 6 from the grading promise and gave it a defined disposition vocabulary (Excluded / Unverified / Deferred / Substituted) — grading a refuted candidate would imply it belongs in the census, and four rows carried no grade at all. Corrected the v1.0.0 changelog entry: Section 2 has seven distribution signals, not six. | | 1.0.7 | 2026-08-13 | Split Section 2 out of the "claims use of libCacheSim" grouping introduced in 1.0.6: stars, package releases and dependency counts are distribution signals, so an A there certifies only that the value was read correctly. Added that grades are not comparable across sections. Parameterized the update checklist by target section — a Section 5 entry cannot supply a libCacheSim-use quote without committing the conflation the rules forbid, and upstream independence is now recorded for Section 3 only. | | 1.0.6 | 2026-08-13 | Redefined the grade rubric in terms of *the relationship each section claims* rather than "use of libCacheSim". The old wording made a Section 5.2 Grade A read as certifying libCacheSim adoption, which is the exact conflation Section 1 forbids; grades there certify a SIEVE implementation and nothing more. Also scoped the pinning claim to the Grade A GitHub links it actually covers — the two Grade U rows are unpinned on purpose, and SkiftOS keeps a branch URL because reproducing its 404 is the evidence. | From 3eb26f674dab16a3471cfb930f4aeb423e92b85a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:38:41 +0000 Subject: [PATCH 13/18] docs: pin arXiv versions, census v1.0.10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three findings, all correct. The SCION entry was labelled v1 but linked the unversioned /abs endpoint, so a later revision could silently change the text behind a Grade A quote. Fixed — and the same exposure existed on the PolicySmith, DynamicAdaptiveClimb and 2DIO links, which are now pinned to the version actually read. The RAC row is the honest exception: its version was not recorded at fetch time, so the row says that rather than guessing v1. That matters most for excluded candidates, since the section already warns that a later version may cite libCacheSim where an earlier one did not. Grade A still required evidence "quoted verbatim" while Section 2 rows are measured values graded A — the definition declared those rows ineligible for the grade they carry. The quotation requirement is now conditional on the evidence being prose. The header likewise promised a verbatim quote for every Section 3-5 entry, but the two Grade U rows deliberately have none: a repository root with no implementing file, and a 404. For those the absence of a quote is the finding, and the header now says so. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 88b99d1f..e98c8fab 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.9 +**Census version:** 1.0.10 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -9,6 +9,10 @@ carries a public URL, the date the evidence was checked, a confidence grade, and itself — a **verbatim quote** in Sections 3–5, and in Section 2 the **measured value**, since a star count or release date is a number to read rather than a sentence to quote. +**Grade U rows are the deliberate exception**: they have no substantiating quote, because the +absence of one is the finding. Those rows record what the source *failed* to show — a repository +root with no implementing file, or a link that now returns 404. + **Section 6 is different by design.** It holds candidates that were checked but did not enter the census, and records a **disposition** rather than a grade — grading a paper that turned out not to mention libCacheSim would imply it belongs here. Only the **Excluded** rows are settled; the @@ -38,7 +42,7 @@ an order of magnitude, and the distinction is the single most important integrit | Grade | Meaning | | --- | --- | -| **A** | Primary source, quoted verbatim, establishes the relationship claimed by that section unambiguously. | +| **A** | Primary source establishes the relationship claimed by that section unambiguously — quoted verbatim where the source is prose, or read directly where it is a measured value (Section 2). | | **B** | Primary source confirms the relationship, but its extent is inferred. | | **C** | Self-reported or aggregate claim with no public per-entry roster to audit. | | **U** | Lead identified, but the cited source does not substantiate it; retained for manual follow-up. | @@ -138,7 +142,7 @@ Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. ### 3.1 PolicySmith — LLM-generated cache policies (UT Austin) - **Artifact:** *Man-Made Heuristics Are Dead. Long Live Code Generators!*, - [arXiv:2510.08803](https://arxiv.org/abs/2510.08803) (2025-10-13). Dwivedula, Saxena, Akella, + [arXiv:2510.08803v1](https://arxiv.org/abs/2510.08803v1) (2025-10-13). Dwivedula, Saxena, Akella, Chaudhuri, Kim. - **Evidence (quoted):** "Our prototype is built on libCacheSim, a high-performance web cache simulator with an event-driven interface." ([full text](https://arxiv.org/html/2510.08803v1)) @@ -167,7 +171,7 @@ Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. ### 3.3 DynamicAdaptiveClimb (Ben-Gurion University et al.) - **Artifact:** *DynamicAdaptiveClimb: Adaptive Cache Replacement with Dynamic Resizing*, - [arXiv:2511.21235v1](https://arxiv.org/abs/2511.21235) (2025-11-26). Berend, Dolev, Kumari, + [arXiv:2511.21235v1](https://arxiv.org/abs/2511.21235v1) (2025-11-26). Berend, Dolev, Kumari, Mishra, Kogan-Sadetsky, Somani. - **Evidence (quoted):** "We conduct all evaluations using libCacheSim, an open-source, high-performance, and extensible cache simulator widely adopted in recent caching research." @@ -179,7 +183,7 @@ Public artifacts that build on, fork, or run libCacheSim. Verified 2026-08-12. ### 3.4 SCION (PingCAP) - **Artifact:** *SCION: Size-aware Policy Orchestration for Nonstationary Object Caches*, - [arXiv:2605.01055v1](https://arxiv.org/abs/2605.01055). Qizhi Wang, PingCAP + [arXiv:2605.01055v1](https://arxiv.org/abs/2605.01055v1). Qizhi Wang, PingCAP Data & AI-Innovation Lab. Submission history on the arXiv abstract page reads "Fri, 27 Mar 2026"; note that this does not match the `2605` (May 2026) identifier prefix. The date above is arXiv's own stated submission date, not an inference from the identifier. @@ -317,8 +321,8 @@ a source supports an entry that belongs in the census, and nothing here does. Th | Candidate | Why it surfaced | Finding | Date checked | Disposition | | --- | --- | --- | --- | --- | -| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim | 2026-08-12 | **Excluded** | -| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971](https://arxiv.org/pdf/2603.19971) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | 2026-08-12 | **Excluded** | +| *RAC: Relation-Aware Cache Replacement for LLMs*, [arXiv:2602.21547](https://arxiv.org/pdf/2602.21547) | Returned by a search for libCacheSim evaluations | Full-text search found no mention of libCacheSim (version current on the check date; the specific version was not recorded) | 2026-08-12 | **Excluded** | +| *2DIO: A Cache-Accurate Storage Microbenchmark*, [arXiv:2603.19971v1](https://arxiv.org/pdf/2603.19971v1) | Returned by a search for libCacheSim usage | Full-text search found no mention of libCacheSim | 2026-08-12 | **Excluded** | | Chameleon Trovi artifact [`1a05c09b…`](https://trovi.chameleoncloud.org/dashboard/artifacts/1a05c09b-f149-4555-b133-a4114155746b) ("Clock-Pro Implementation on libCacheSim") | Title indicates libCacheSim use | Page is client-rendered; content could not be retrieved by fetch, and the API path returned 404 | 2026-08-12 | **Unverified** | | Chameleon Trovi artifact [`bac62a10…`](https://trovi.chameleoncloud.org/dashboard/artifacts/bac62a10-3868-4a77-9075-7e9247dd199b) ("Clock with Adaptive Replacement Cache Implementation") | Title indicates libCacheSim use | Same as above | 2026-08-12 | **Unverified** | | PyPI download statistics | Would quantify consumption | pypistats.org returned HTTP 429 | 2026-08-12 | **Deferred** | @@ -379,7 +383,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.9}, + version = {1.0.10}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -388,7 +392,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.9, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.10, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -400,6 +404,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.10 | 2026-08-13 | Pinned every arXiv link to the version actually read: SCION was labelled v1 but linked the unversioned endpoint, and the PolicySmith, DynamicAdaptiveClimb and 2DIO links had the same exposure. The RAC row now states that its version was not recorded rather than implying one. Made the Grade A definition allow measured evidence, since Section 2 rows are read rather than quoted, and exempted Grade U rows from the verbatim-quote promise — for those, the absence of a quote is the finding. | | 1.0.9 | 2026-08-13 | Stopped describing all of Section 6 as rejected: only the Excluded rows are settled, while Unverified and Deferred rows are open follow-up work and now point at the next-revision priorities, so a maintainer does not skip them. Narrowed the evidence promise — Section 2 records a measured value, not a verbatim quote, since a star count is a number to read rather than a sentence to quote; the update checklist says the same. Scoped the README's grade promise to match. | | 1.0.8 | 2026-08-13 | Exempted Section 6 from the grading promise and gave it a defined disposition vocabulary (Excluded / Unverified / Deferred / Substituted) — grading a refuted candidate would imply it belongs in the census, and four rows carried no grade at all. Corrected the v1.0.0 changelog entry: Section 2 has seven distribution signals, not six. | | 1.0.7 | 2026-08-13 | Split Section 2 out of the "claims use of libCacheSim" grouping introduced in 1.0.6: stars, package releases and dependency counts are distribution signals, so an A there certifies only that the value was read correctly. Added that grades are not comparable across sections. Parameterized the update checklist by target section — a Section 5 entry cannot supply a libCacheSim-use quote without committing the conflation the rules forbid, and upstream independence is now recorded for Section 3 only. | From 708dd96a110095bf1f70ec6506a524cbe220f56c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:42:34 +0000 Subject: [PATCH 14/18] docs: qualify the re-verification rule, census v1.0.11 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two contradictions, both correct. The header called every Section 6 candidate "checked", while the disposition table defines Unverified as "could not be checked at all" — the two Trovi rows are exactly that. They are now described as investigated, and the Date checked column is stated to mean the date the check was made or attempted, which is what it has always held for those rows. More consequential: rule 4 moved anything failing re-verification into Section 6, unconditionally. The SkiftOS 404 is such a failure and is deliberately kept in Section 5.2 as a Grade U lead, because the 404 is the evidence that a published adopters list has rotted. A maintainer following the checklist would have undone that. The rule now splits by failure mode: refuted sources move to Section 6 as Excluded; unreachable ones are downgraded to U in place when the entry sits in a named list where its absence is informative, with SkiftOS named as the worked example. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index e98c8fab..e3d37f82 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.10 +**Census version:** 1.0.11 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -13,8 +13,9 @@ star count or release date is a number to read rather than a sentence to quote. absence of one is the finding. Those rows record what the source *failed* to show — a repository root with no implementing file, or a link that now returns 404. -**Section 6 is different by design.** It holds candidates that were checked but did not enter the -census, and records a **disposition** rather than a grade — grading a paper that turned out not to +**Section 6 is different by design.** It holds candidates that were **investigated** but did not +enter the census — some refuted, some never reachable at all — and records a **disposition** +rather than a grade — grading a paper that turned out not to mention libCacheSim would imply it belongs here. Only the **Excluded** rows are settled; the **Unverified** and **Deferred** rows are open follow-up work, and appear in the [next-revision priorities](#7-how-to-update-this-census). Nothing in the section is deleted, so a @@ -305,9 +306,13 @@ accurate when added, then drift as the linked code moves. ## 6. Checked and excluded -Recorded so that future revisions do not re-investigate the same dead ends. The `Date checked` -column matters most here: a dead end is only worth trusting as recently as its last check, and a -paper that did not mention libCacheSim in one snapshot may cite it in a later version. +Investigated candidates that did not enter the census. Recorded so that a later revision knows +which dead ends are settled and which are still open — **Excluded** rows need no re-work, while +**Unverified** and **Deferred** rows are waiting for someone with a way through. + +The `Date checked` column is when the check was *made or attempted*, and it matters most here: a +dead end is only worth trusting as recently as that date, and a paper that did not mention +libCacheSim in one version may cite it in a later one. These rows carry a **disposition**, not a confidence grade — the A/B/C/U rubric measures how well a source supports an entry that belongs in the census, and nothing here does. The vocabulary: @@ -344,8 +349,15 @@ a source supports an entry that belongs in the census, and nothing here does. Th third-party validation from the project's own work, and it is meaningless for the others. 3. Re-fetch every source before restating it. Do not carry an unverified entry forward with a fresh date. -4. Move anything that fails re-verification into [Section 6](#6-checked-and-excluded) with the - reason, rather than deleting it. +4. When a source fails re-verification, the response depends on *how* it failed. Never delete + either way: + - **Refuted** — the source is reachable but does not support the claim → move the entry to + [Section 6](#6-checked-and-excluded) as **Excluded**, with the reason. + - **Unreachable** — 404, paywall, or withdrawn → **downgrade to Grade U in place** and record + what failed, when the entry sits in a named list where its absence is itself informative. + SkiftOS in Section 5.2 is the worked example: the 404 is the finding, and moving the row to + Section 6 would hide that a published adopters list has rotted. Move an unreachable entry to + Section 6 only when it has no place in a census table to begin with. 5. Keep Sections 3 and 5 strictly separate: simulator use versus algorithm use. 6. Add a row to the changelog below. @@ -383,7 +395,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.10}, + version = {1.0.11}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -392,7 +404,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.10, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.11, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -404,6 +416,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.11 | 2026-08-13 | Stopped calling every Section 6 candidate "checked" — two were never reachable, which the Unverified definition says outright; they are *investigated* instead, and the `Date checked` column is stated to mean checked-or-attempted. Qualified the failed-re-verification rule: a refuted source moves to Section 6, but an unreachable one is downgraded to Grade U in place when its absence is informative, as with the SkiftOS 404. The unconditional rule would have told a maintainer to undo that row. | | 1.0.10 | 2026-08-13 | Pinned every arXiv link to the version actually read: SCION was labelled v1 but linked the unversioned endpoint, and the PolicySmith, DynamicAdaptiveClimb and 2DIO links had the same exposure. The RAC row now states that its version was not recorded rather than implying one. Made the Grade A definition allow measured evidence, since Section 2 rows are read rather than quoted, and exempted Grade U rows from the verbatim-quote promise — for those, the absence of a quote is the finding. | | 1.0.9 | 2026-08-13 | Stopped describing all of Section 6 as rejected: only the Excluded rows are settled, while Unverified and Deferred rows are open follow-up work and now point at the next-revision priorities, so a maintainer does not skip them. Narrowed the evidence promise — Section 2 records a measured value, not a verbatim quote, since a star count is a number to read rather than a sentence to quote; the update checklist says the same. Scoped the README's grade promise to match. | | 1.0.8 | 2026-08-13 | Exempted Section 6 from the grading promise and gave it a defined disposition vocabulary (Excluded / Unverified / Deferred / Substituted) — grading a refuted candidate would imply it belongs in the census, and four rows carried no grade at all. Corrected the v1.0.0 changelog entry: Section 2 has seven distribution signals, not six. | From a04817130ad4f5b4ed32efc4d4ef6d02dc4dbebd Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:42:51 +0000 Subject: [PATCH 15/18] docs: fix sentence flow in the Section 6 header note The previous edit left three em-dashes in one sentence. No change in meaning. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index e3d37f82..e008b0e4 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -14,9 +14,9 @@ absence of one is the finding. Those rows record what the source *failed* to sho root with no implementing file, or a link that now returns 404. **Section 6 is different by design.** It holds candidates that were **investigated** but did not -enter the census — some refuted, some never reachable at all — and records a **disposition** -rather than a grade — grading a paper that turned out not to -mention libCacheSim would imply it belongs here. Only the **Excluded** rows are settled; the +enter the census: some refuted, some never reachable at all. Those rows record a **disposition** +rather than a grade, because grading a paper that turned out not to mention libCacheSim would +imply it belongs here. Only the **Excluded** rows are settled; the **Unverified** and **Deferred** rows are open follow-up work, and appear in the [next-revision priorities](#7-how-to-update-this-census). Nothing in the section is deleted, so a later revision can tell a refuted candidate from one that was never checked. From 5940bef75e4a689b0b788424553098274d162b5b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:47:34 +0000 Subject: [PATCH 16/18] docs: rename Section 6 to Investigated candidates, census v1.0.12 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The heading still said "Checked and excluded" after the body was corrected twice. Two of its rows were never checked, and three of the six are not excluded — Unverified, Deferred and Substituted all mean something else. A maintainer navigating by headings could write the section off as settled dead ends and skip the follow-up work the priority list asks for. Renamed to "Investigated candidates", which covers refuted, unreachable and deferred alike. Internal anchors updated; all internal links verified to resolve. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index e008b0e4..3a735b7f 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.11 +**Census version:** 1.0.12 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -304,7 +304,7 @@ accurate when added, then drift as the linked code moves. --- -## 6. Checked and excluded +## 6. Investigated candidates Investigated candidates that did not enter the census. Recorded so that a later revision knows which dead ends are settled and which are still open — **Excluded** rows need no re-work, while @@ -352,7 +352,7 @@ a source supports an entry that belongs in the census, and nothing here does. Th 4. When a source fails re-verification, the response depends on *how* it failed. Never delete either way: - **Refuted** — the source is reachable but does not support the claim → move the entry to - [Section 6](#6-checked-and-excluded) as **Excluded**, with the reason. + [Section 6](#6-investigated-candidates) as **Excluded**, with the reason. - **Unreachable** — 404, paywall, or withdrawn → **downgrade to Grade U in place** and record what failed, when the entry sits in a named list where its absence is itself informative. SkiftOS in Section 5.2 is the worked example: the 404 is the finding, and moving the row to @@ -395,7 +395,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.11}, + version = {1.0.12}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -404,7 +404,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.11, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.12, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -416,6 +416,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.12 | 2026-08-13 | Renamed Section 6 from "Checked and excluded" to "Investigated candidates". Two of its rows were never checked and three are not excluded, so a maintainer navigating by heading could have written the whole section off as settled and skipped the open follow-up work. Internal anchors updated to match. | | 1.0.11 | 2026-08-13 | Stopped calling every Section 6 candidate "checked" — two were never reachable, which the Unverified definition says outright; they are *investigated* instead, and the `Date checked` column is stated to mean checked-or-attempted. Qualified the failed-re-verification rule: a refuted source moves to Section 6, but an unreachable one is downgraded to Grade U in place when its absence is informative, as with the SkiftOS 404. The unconditional rule would have told a maintainer to undo that row. | | 1.0.10 | 2026-08-13 | Pinned every arXiv link to the version actually read: SCION was labelled v1 but linked the unversioned endpoint, and the PolicySmith, DynamicAdaptiveClimb and 2DIO links had the same exposure. The RAC row now states that its version was not recorded rather than implying one. Made the Grade A definition allow measured evidence, since Section 2 rows are read rather than quoted, and exempted Grade U rows from the verbatim-quote promise — for those, the absence of a quote is the finding. | | 1.0.9 | 2026-08-13 | Stopped describing all of Section 6 as rejected: only the Excluded rows are settled, while Unverified and Deferred rows are open follow-up work and now point at the next-revision priorities, so a maintainer does not skip them. Narrowed the evidence promise — Section 2 records a measured value, not a verbatim quote, since a star count is a number to read rather than a sentence to quote; the update checklist says the same. Scoped the README's grade promise to match. | From e15b82c93d22d915f5b7d1f444e94545f8f20894 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:50:38 +0000 Subject: [PATCH 17/18] docs: correct the v1.0.5 changelog claim, census v1.0.13 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v1.0.5 entry claimed every GitHub link in Section 5.2 had been pinned. It had not: the Pelikan and SkiftOS rows were unpinned in that revision and still are, deliberately. A changelog exists to audit what each revision actually established, so an overstated entry there is worse than elsewhere — it misrepresents the historical record rather than the current state. Scoped to the Grade A links it really covered. The README also still said "checked" where Section 6 says "investigated"; two of those candidates were never checked at all. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- README.md | 2 +- doc/adoption-census.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6247249d..b9b6c10f 100644 --- a/README.md +++ b/README.md @@ -384,7 +384,7 @@ We provide a more comprehensive cache datasets at [https://github.com/cacheMon/c See the [adoption census](/doc/adoption-census.md) for a source-linked inventory of documented libCacheSim adoption — research artifacts built on it, distribution channels, and downstream adoption of algorithms designed in it. Every census entry carries its evidence, source URL, -verification date, and confidence grade; candidates that were checked but did not qualify are kept +verification date, and confidence grade; candidates that were investigated but did not qualify are kept in a separate section with a disposition instead, so they are not silently dropped. --- diff --git a/doc/adoption-census.md b/doc/adoption-census.md index 3a735b7f..edc8feb9 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.12 +**Census version:** 1.0.13 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -395,7 +395,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.12}, + version = {1.0.13}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -404,7 +404,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.12, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.13, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -416,6 +416,7 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.13 | 2026-08-13 | Corrected the v1.0.5 changelog entry, which claimed every GitHub link in Section 5.2 was pinned — the two Grade U rows were not, then or now. A changelog that audits what each revision established has to be accurate about it. Also changed the README from "checked" to "investigated", matching the Section 6 vocabulary. | | 1.0.12 | 2026-08-13 | Renamed Section 6 from "Checked and excluded" to "Investigated candidates". Two of its rows were never checked and three are not excluded, so a maintainer navigating by heading could have written the whole section off as settled and skipped the open follow-up work. Internal anchors updated to match. | | 1.0.11 | 2026-08-13 | Stopped calling every Section 6 candidate "checked" — two were never reachable, which the Unverified definition says outright; they are *investigated* instead, and the `Date checked` column is stated to mean checked-or-attempted. Qualified the failed-re-verification rule: a refuted source moves to Section 6, but an unreachable one is downgraded to Grade U in place when its absence is informative, as with the SkiftOS 404. The unconditional rule would have told a maintainer to undo that row. | | 1.0.10 | 2026-08-13 | Pinned every arXiv link to the version actually read: SCION was labelled v1 but linked the unversioned endpoint, and the PolicySmith, DynamicAdaptiveClimb and 2DIO links had the same exposure. The RAC row now states that its version was not recorded rather than implying one. Made the Grade A definition allow measured evidence, since Section 2 rows are read rather than quoted, and exempted Grade U rows from the verbatim-quote promise — for those, the absence of a quote is the finding. | @@ -423,7 +424,7 @@ For reading rather than citing, the current version always lives at | 1.0.8 | 2026-08-13 | Exempted Section 6 from the grading promise and gave it a defined disposition vocabulary (Excluded / Unverified / Deferred / Substituted) — grading a refuted candidate would imply it belongs in the census, and four rows carried no grade at all. Corrected the v1.0.0 changelog entry: Section 2 has seven distribution signals, not six. | | 1.0.7 | 2026-08-13 | Split Section 2 out of the "claims use of libCacheSim" grouping introduced in 1.0.6: stars, package releases and dependency counts are distribution signals, so an A there certifies only that the value was read correctly. Added that grades are not comparable across sections. Parameterized the update checklist by target section — a Section 5 entry cannot supply a libCacheSim-use quote without committing the conflation the rules forbid, and upstream independence is now recorded for Section 3 only. | | 1.0.6 | 2026-08-13 | Redefined the grade rubric in terms of *the relationship each section claims* rather than "use of libCacheSim". The old wording made a Section 5.2 Grade A read as certifying libCacheSim adoption, which is the exact conflation Section 1 forbids; grades there certify a SIEVE implementation and nothing more. Also scoped the pinning claim to the Grade A GitHub links it actually covers — the two Grade U rows are unpinned on purpose, and SkiftOS keeps a branch URL because reproducing its 404 is the evidence. | -| 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link in Section 5.2 is now pinned; only the PostgREST docs URL remains mutable. | +| 1.0.5 | 2026-08-13 | Pinned the 3L-Cache README quote to revision `134cd15`, since that quote is also repository text that can change. Replaced the immudb evidence link: a merged pull request is not immutable, since GitHub titles stay editable after merge, so quoting a PR title is not a durable citation. The row now cites `embedded/cache/cache.go` pinned at `1a5f54e`, verified to read "Cache implements the SIEVE cache replacement policy" with a `hand` pointer and per-entry `visited` flags. Every GitHub link backing a Grade A row in Section 5.2 is now pinned; the two Grade U rows stay unpinned by design and the PostgREST docs URL remains mutable. | | 1.0.4 | 2026-08-13 | Added the missing `Date checked` column to Section 6, completing the coverage the introduction promises: every table in the document now records when its evidence was last checked. Noted why that column matters most for excluded candidates — a dead end is only trustworthy as of its last check, and a paper may cite libCacheSim in a later version. | | 1.0.3 | 2026-08-13 | Pinned six of the seven GitHub evidence links in Section 5.2 to commit SHAs via `git ls-remote`, closing most of limitation 5 rather than deferring it; re-fetched the pinned TiDB and Ceph URLs to confirm the quoted text is present at those revisions. Limitation 5 now covers only the PostgREST `latest` docs URL. Added pinning to the update protocol as a standing rule. | | 1.0.2 | 2026-08-13 | Added the missing `Date checked` column to Section 5.1. Recorded a new limitation 5: Section 5.2's evidence links are branch URLs, not commit permalinks, so they can drift from what was verified — the SkiftOS 404 is that failure already realized. Pinning was attempted and blocked by the snapshot environment (`api.github.com` returned 403; blob pages render SHAs client-side), so the method is documented for the next revision instead of being left implicit. | From 939052f0dcb3b88696dfb065ad56c293446f7e41 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 00:54:34 +0000 Subject: [PATCH 18/18] docs: correct a count in the v1.0.12 changelog, census v1.0.14 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Section 6 holds two Excluded, two Unverified, one Deferred and one Substituted row, so four of six are not excluded — the entry said three, dropping the Substituted row. Counted from the table. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi --- doc/adoption-census.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/adoption-census.md b/doc/adoption-census.md index edc8feb9..e8536bf1 100644 --- a/doc/adoption-census.md +++ b/doc/adoption-census.md @@ -1,6 +1,6 @@ # libCacheSim Adoption Census -**Census version:** 1.0.13 +**Census version:** 1.0.14 **Snapshot date:** 2026-08-13 **Maintained at:** `doc/adoption-census.md` in [1a1a11a/libCacheSim](https://github.com/1a1a11a/libCacheSim) @@ -395,7 +395,7 @@ Then substitute it for ``: ```bibtex @misc{libcachesim-adoption-census, title = {libCacheSim Adoption Census}, - version = {1.0.13}, + version = {1.0.14}, howpublished = {\url{https://github.com/1a1a11a/libCacheSim/blob//doc/adoption-census.md}}, note = {Snapshot dated 2026-08-13}, year = {2026} @@ -404,7 +404,7 @@ Then substitute it for ``: Plain-text form: -> libCacheSim Adoption Census, version 1.0.13, snapshot 2026-08-13, +> libCacheSim Adoption Census, version 1.0.14, snapshot 2026-08-13, > `doc/adoption-census.md` in github.com/1a1a11a/libCacheSim at commit ``. For reading rather than citing, the current version always lives at @@ -416,8 +416,9 @@ For reading rather than citing, the current version always lives at | Version | Date | Change | | --- | --- | --- | +| 1.0.14 | 2026-08-13 | Corrected an undercount in the v1.0.12 changelog entry: four of Section 6's six rows are not excluded (two Unverified, one Deferred, one Substituted), not three. | | 1.0.13 | 2026-08-13 | Corrected the v1.0.5 changelog entry, which claimed every GitHub link in Section 5.2 was pinned — the two Grade U rows were not, then or now. A changelog that audits what each revision established has to be accurate about it. Also changed the README from "checked" to "investigated", matching the Section 6 vocabulary. | -| 1.0.12 | 2026-08-13 | Renamed Section 6 from "Checked and excluded" to "Investigated candidates". Two of its rows were never checked and three are not excluded, so a maintainer navigating by heading could have written the whole section off as settled and skipped the open follow-up work. Internal anchors updated to match. | +| 1.0.12 | 2026-08-13 | Renamed Section 6 from "Checked and excluded" to "Investigated candidates". Two of its rows were never checked and four of the six are not excluded, so a maintainer navigating by heading could have written the whole section off as settled and skipped the open follow-up work. Internal anchors updated to match. | | 1.0.11 | 2026-08-13 | Stopped calling every Section 6 candidate "checked" — two were never reachable, which the Unverified definition says outright; they are *investigated* instead, and the `Date checked` column is stated to mean checked-or-attempted. Qualified the failed-re-verification rule: a refuted source moves to Section 6, but an unreachable one is downgraded to Grade U in place when its absence is informative, as with the SkiftOS 404. The unconditional rule would have told a maintainer to undo that row. | | 1.0.10 | 2026-08-13 | Pinned every arXiv link to the version actually read: SCION was labelled v1 but linked the unversioned endpoint, and the PolicySmith, DynamicAdaptiveClimb and 2DIO links had the same exposure. The RAC row now states that its version was not recorded rather than implying one. Made the Grade A definition allow measured evidence, since Section 2 rows are read rather than quoted, and exempted Grade U rows from the verbatim-quote promise — for those, the absence of a quote is the finding. | | 1.0.9 | 2026-08-13 | Stopped describing all of Section 6 as rejected: only the Excluded rows are settled, while Unverified and Deferred rows are open follow-up work and now point at the next-revision priorities, so a maintainer does not skip them. Narrowed the evidence promise — Section 2 records a measured value, not a verbatim quote, since a star count is a number to read rather than a sentence to quote; the update checklist says the same. Scoped the README's grade promise to match. |