docs: add source-linked adoption census - #322
Conversation
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
|
CI note: the
Two distinct macOS breakages are visible, both environmental rather than change-related:
Both look worth fixing, but they're outside the scope of a documentation PR, so I haven't touched them here. Happy to open a separate PR for either if that's useful. Generated by Claude Code |
There was a problem hiding this comment.
Pull request overview
Adds a new, versioned “adoption census” document to the doc/ tree and links it from the main README and the docs index so readers can find source-linked evidence of libCacheSim adoption.
Changes:
- Add
doc/adoption-census.mdwith a versioned snapshot, methodology, and source-linked evidence tables. - Link the census from
README.md(“Who uses libCacheSim” section). - Add the census to the
doc/README.mddocumentation index.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | Adds a “Who uses libCacheSim” section linking to the adoption census. |
| doc/README.md | Adds the adoption census to the docs index under a new “Project” section. |
| doc/adoption-census.md | Introduces the versioned, source-linked adoption census document and citation guidance. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| 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} |
There was a problem hiding this comment.
Good catch — fixed in d519fe5.
The example now models the immutable form (blob/<commit-sha>/doc/adoption-census.md) and includes the command to get the SHA: git log -1 --format=%H -- doc/adoption-census.md. The blob/develop URL is kept but relabeled as the read-latest link, explicitly separated from the citation form.
Generated by Claude Code
There was a problem hiding this comment.
Follow-up: the review comments on Section 5.2 (grades, Pelikan link) and the SCION date are addressed in 449ffd2 and 64ed72c. Summary in the thread replies below.
Generated by Claude Code
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 <commit-sha> 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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8a48cb83d0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### 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 |
There was a problem hiding this comment.
An arXiv identifier beginning with 2605 was assigned in May 2026, so 2026-03-27 cannot be the submission date for arXiv:2605.01055v1. This makes the source-linked artifact metadata inaccurate and inconsistent with the dates used for the other arXiv entries; use the v1 submission date, or explicitly label this as a separate manuscript date if that is what it represents.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
The reasoning about arXiv identifiers is sound, but the primary source disagrees, so I kept the date and documented the conflict instead of "correcting" it.
The submission history on arxiv.org/abs/2605.01055 reads "Fri, 27 Mar 2026 23:56:50 UTC" for v1 — that is arXiv's own stated v1 date, not an inference of mine, and the paper's HTML gives the same date. So the 2605 prefix and the stated submission date genuinely disagree at the source.
449ffd2 cites the abstract page rather than the HTML, and adds: "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." A reader who spots the same mismatch now finds it already flagged.
Generated by Claude Code
| | System | Evidence link | | ||
| | --- | --- | |
There was a problem hiding this comment.
The census introduction and README promise a confidence grade for every entry, and the methodology defines those grades, but this table has no grade column for any of its ten adopter claims. Readers therefore cannot tell whether these claims are primary-source confirmations or merely inherited from the SIEVE authors' list; add a grade per row or narrow the document's advertised grading guarantee.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 449ffd2 — and the check turned up more than a missing column.
Rather than grade the rows as inherited from the SIEVE authors' list, I fetched all ten links individually. Eight resolve to a primary artifact naming SIEVE and are now Grade A, each with the quoted evidence in a new "What the fetch showed" column (immudb's PR title, TiDB's type Sieve[K comparable, V any] struct, Ceph's "based on SIEVE [0]", PostgREST's docs sentence, the Go/Rust/Python imports, and Dragonfly's comment linking the NSDI '24 paper).
Two are downgraded to U: Pelikan (see the adjacent thread) and SkiftOS, whose linked path now returns HTTP 404 — link rot since the entry was added. The verification protocol now states that third-party lists are treated as leads, not evidence, which is exactly how those two surfaced.
Generated by Claude Code
| | --- | --- | | ||
| | 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) | |
There was a problem hiding this comment.
The text immediately above the table says every entry links to a specific implementing file or pull request, but the Pelikan entry links only to the repository root. That target does not identify where Pelikan implements SIEVE and thus does not independently substantiate this adoption claim under the census's stated evidence standard; replace it with an exact file, commit, or PR.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, and I couldn't find a replacement link. Searching for Pelikan's SIEVE implementation turns up only the claim that a variant of SIEVE is used in Segcache — no specific file, commit, or PR.
Since the evidence doesn't exist to meet the stated standard, 449ffd2 downgrades Pelikan to Grade U and records why ("upstream list links only the repository root; no specific implementing file located") rather than relaxing the standard to fit the entry. It stays in the table as a lead — it may well be a genuine adopter — but it no longer counts as substantiated.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d519fe534e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 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 | |
There was a problem hiding this comment.
The linked Harvard news article is not a primary source for adoption by Android, TiDB, or the unnamed systems, and this is an aggregate claim without a public per-entry roster—the document's own definition of Grade C. Labeling it Grade B overstates the evidence strength; either provide primary implementation evidence for the claimed relationships or grade the aggregate statement C.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Agreed — downgraded to C in 64ed72c.
The B came from reasoning about editorial independence: a university news office isn't the researcher's own bio page. But the rubric grades auditability, not who vouches for the claim, and by that definition an aggregate with no per-entry roster is C regardless of publisher. The doc now says so explicitly so the next revision doesn't relitigate it, and notes that TiDB — one of the systems the claim names — is independently verified at Grade A in Section 5.2, while the aggregate figures around it are not.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 64ed72c8f9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 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 | |
There was a problem hiding this comment.
The TiDB evidence URL uses blob/master, and most other file-level evidence in this table similarly uses main or master. When those branches change, a cited census snapshot may link to content different from what was verified—or to another 404—so its Grade A claims are no longer reproducible. Pin these evidence links to the commit revisions fetched on 2026-08-13, just as the census itself requires a commit permalink.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, and it's the sharpest finding in this review — it's the same rule the census imposes on its own citation, applied to its evidence, and the SkiftOS row is that failure already realized rather than hypothetical.
I tried to pin them and couldn't from this environment:
api.github.com/repos/pingcap/tidb/commits?path=...&per_page=1→ HTTP 403 (proxy-blocked here)- the blob page renders the commit SHA client-side, so nothing readable comes back from a fetch
- the GitHub tools in this session are scoped to this repository, so they can't query pingcap/tidb, ceph/ceph, etc.
Rather than fabricate revisions or quietly leave the weakness unstated, f092eec records it as limitation 5 with the exact command to close it (git ls-remote, or GET /repos/{owner}/{repo}/commits?path={file}&per_page=1, rewriting blob/main/... → blob/{sha}/...), promotes it to second place in the next-revision priority list, and adds the caveat that Section 5.2's Grade A entries are verified as of 2026-08-13 rather than permanently reproducible.
Worth noting for whoever picks this up: limitations 4 and 5 are both blocked by the environment, not the sources. One re-run from a host with unrestricted access to api.github.com, pypistats.org and usenix.org closes three open items at once — that's now in the doc too.
Generated by Claude Code
There was a problem hiding this comment.
Update — this is now actually done, not deferred. I was wrong that the environment blocked it: api.github.com is 403 here, but git ls-remote works, and that's sufficient to resolve branch heads.
55bb261 pins six of the seven GitHub file links to commit SHAs:
| System | Pinned revision |
|---|---|
| TiDB | d5f9ca5690c0a53cac36002f9d2d2bdcba25f4fc |
| Nyrkiö | f17320128b357c1d18c7f7b889a3f3d2b3115120 |
| Dragonfly | f4019d7fec0ddcd1e6484dd6eeade7d52b146af6 |
| dnscrypt-proxy | 1a3ace9ac88461f76e1e66d1270ae645cbe2993b |
| encrypted-dns-server | 3754243bf96db5873ab49b58c057f00ef3a16a52 |
| Ceph | 5995d21863b3992bd9f463b5a0f774869351be36 |
I re-fetched the pinned TiDB and Ceph URLs afterwards to confirm the quoted text is actually present at those revisions, rather than assuming the pin is faithful.
Limitation 5 now covers only what genuinely remains: the PostgREST link tracks docs.postgrest.org/en/latest/, so it needs a versioned docs URL. The immudb link is a merged PR and needs no pin, and SkiftOS keeps its branch URL because reproducing the 404 is the evidence for its U grade. Pinning is now a standing rule in the update protocol.
Generated by Claude Code
| | 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 | |
There was a problem hiding this comment.
When this snapshot is audited or refreshed, these two rows have neither a Date checked column nor a surrounding statement giving their verification date. They therefore violate the document and README guarantee that every entry records when its evidence was checked, and an updater cannot distinguish a source verified for this snapshot from one merely carried forward. Record the fetch date for each claim, as Section 4 does.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in f092eec — Section 5.1 now carries a Date checked column (2026-08-12 for both rows), matching Section 4.
You're right that the omission was the kind that bites an updater rather than a reader: without it, a carried-forward source is indistinguishable from one verified for this snapshot, which is exactly the failure mode rule 3 of the update protocol exists to prevent.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 55bb2611c1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Candidate | Why it surfaced | Finding | Disposition | | ||
| | --- | --- | --- | --- | |
There was a problem hiding this comment.
The Section 6 rows have no verification-date field, even though the README and lines 7–9 promise a date for every entry and this section exists specifically to prevent future re-investigation. When a later census is refreshed, maintainers cannot distinguish a recently verified dead end from a stale result carried forward from an earlier snapshot; add a Date checked column for these excluded and deferred candidates.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 34a995c. Section 6 now carries a Date checked column (2026-08-12 for all six rows).
It was the last table with neither a column nor a surrounding date statement, so coverage is now complete: Sections 2, 3 and 5.2 carry the date in the sentence introducing each table, and Sections 4, 5.1 and 6 carry a per-row column.
I also added a line on why the date matters most in this particular section — a stale exclusion is worse than no exclusion, since a paper that didn't mention libCacheSim in one snapshot may cite it in a later version. Without a date, a future maintainer can't tell whether re-checking is warranted, which defeats the section's whole purpose.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 34a995cec1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - The **immudb** entry links a merged pull request, whose title and merge state are already | ||
| immutable; no pin is needed. |
There was a problem hiding this comment.
The new post-fix rationale says the merged PR's title is immutable, but GitHub PR titles can still be edited after merge. If that happens, PR #1971 will no longer reliably display the quoted “Replace LRU with SIEVE replacement policy” evidence, so this Grade A entry can drift despite the census's snapshot guarantee; link to an immutable commit or file revision that demonstrates the implementation instead.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
You're right, and this also invalidates the claim I made in the previous round that the PR link needed no pin. Fixed in 2f20988.
The immudb row now cites embedded/cache/cache.go at 1a5f54e, verified at that revision to read "Cache implements the SIEVE cache replacement policy", with a hand pointer and per-entry visited flags. That's stronger evidence than the PR title was — it shows the algorithm itself rather than a description of a change to it.
Applying the same reasoning outward, one more link had the same exposure: the 3L-Cache entry in Section 3.2 quotes README text through a repository-root link. It's now pinned at 134cd15, and the quote is corrected to match that revision verbatim — the README says "3L Cache" unhyphenated there, where I'd written "3L-Cache".
Section 5.2 now has no unpinned GitHub links at all. Only the PostgREST docs URL remains mutable, and limitation 5 records why. The update protocol gains the rule that falls out of this: cite the code, not the pull request, with refs/pull/{n}/head noted for when a specific PR revision is genuinely the right target.
Generated by Claude Code
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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2f20988f16
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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 |
There was a problem hiding this comment.
The final tree still contains two unpinned GitHub links in this table: Pelikan links to a repository root and SkiftOS uses blob/main (lines 249–250), so the statement that every GitHub link is commit-pinned and cannot drift is false. This is fresh evidence after the earlier pinning fix, and it also makes the claim that PostgREST is the sole exception inaccurate; qualify it as applying only to the Grade A GitHub evidence, or pin/relocate the two Grade U leads.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — I overclaimed. Fixed in f1ef04c.
The claim is now scoped to what it actually covers: every GitHub link backing a Grade A row in Section 5.2 is pinned. The three exceptions are listed with the reason each is exempt rather than pending:
- PostgREST (Grade A) — not a GitHub link at all; it tracks
docs.postgrest.org/en/latest/. This is the one genuinely worth fixing. - Pelikan (Grade U) — links a repository root because no implementing file was located. Pinning the root would manufacture false precision around an entry whose whole point is that it isn't substantiated.
- SkiftOS (Grade U) — deliberately keeps
blob/main, because reproducing the 404 is the evidence for its grade. A pinned SHA would resolve to a revision where the file still existed, hiding the link rot the row documents.
So two of the three aren't a backlog item — pinning them would make the census less accurate, and the doc now says so rather than leaving them looking overlooked.
Generated by Claude Code
|
|
||
| | Grade | Meaning | | ||
| | --- | --- | | ||
| | **A** | Primary source, quoted verbatim, states use of libCacheSim unambiguously. | |
There was a problem hiding this comment.
Grade A is defined specifically as evidence that a project uses libCacheSim, yet Section 5 assigns A to projects whose evidence only establishes adoption of SIEVE and explicitly says they are not libCacheSim users. Readers applying this rubric would therefore interpret those grades as confirming the exact relationship the document warns against conflating; define A in terms of unambiguous primary evidence for the relevant claimed relationship, or introduce a separate algorithm-lineage rubric.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
This is the best finding in the whole review — the rubric contradicted the document's central rule. Fixed in f1ef04c.
Grade A said "states use of libCacheSim unambiguously", while Section 5.2 assigns A to projects the same document explicitly says are not libCacheSim users. A reader applying the rubric literally would have drawn precisely the conclusion Section 1 forbids, which is worse than an ungraded table: it would have lent false precision to the conflation.
Grades are now defined against the relationship each section claims, with the split stated outright:
- Sections 2–4 claim use of libCacheSim.
- Section 5 claims adoption of an algorithm designed in libCacheSim, so an A there certifies a SIEVE implementation and says nothing about libCacheSim use.
I chose this over a second rubric because two grade scales invite mixing them up, and the fix is really that the grades were always about "the claimed relationship" — the definition just named the wrong one. Section 5.2 now repeats the caveat above its table, so a reader landing there from a deep link doesn't need to have read Section 1 to avoid the trap.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f1ef04c55f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **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. |
There was a problem hiding this comment.
Section 2 records publication and repository signals, not use of libCacheSim: a GitHub star, package publication, or existence of a binding repository does not establish that anyone uses the simulator. Declaring that Sections 2–4 all claim use makes those Grade A rows read as unambiguous adoption evidence and recreates the category inflation the methodology is intended to prevent; define Section 2's graded relationship separately and reserve the use claim for Sections 3–4.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Right — my 1.0.6 fix re-created the same problem one layer up. Fixed in 2d1dba6.
Section 2 now has its own claim: the value was measured as stated on the date given. Stars, package releases and dependency counts describe how libCacheSim is distributed, not that anyone runs it, so an A there means the number was read correctly and nothing more. The section header says the same thing so a reader skimming the table isn't misled by the A column.
I also added the corollary your point implies: grades are not comparable across sections. Counting every A in the document as an adopter would inflate the census with star counts and SIEVE ports — which is the exact failure the rubric exists to prevent, so it's worth stating rather than leaving to inference.
Generated by Claude Code
| 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. |
There was a problem hiding this comment.
This checklist applies to every new entry but still requires a quote showing libCacheSim use and an upstream-independence assessment. A legitimate Section 5 entry is specifically an algorithm adopter that need not use libCacheSim, so it cannot satisfy this update rule without contradicting the census's central separation; make the required quote describe the relationship claimed by the target section and limit the independence field to direct-user entries.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct — the checklist made a valid Section 5 entry impossible to add without breaking rule 5. Fixed in 2d1dba6.
Rule 2 now asks for a quote establishing the relationship the target section claims: libCacheSim use for Sections 3–4, an algorithm implementation for Section 5, the measured value for Section 2. It says explicitly not to demand a libCacheSim-use quote from a Section 5 entry, since an algorithm adopter need not be a libCacheSim user and requiring one would force exactly the conflation the rules forbid.
Upstream independence is now recorded for Section 3 entries only. That field exists to separate third-party validation from the project's own work — it's what makes the CacheBench caveat meaningful — and it has no meaning for a SIEVE port or a package release.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2d1dba6d14
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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 |
There was a problem hiding this comment.
The fresh remaining case after Section 5.2 was graded is Section 6: its table has no confidence-grade column, four rows are only marked Excluded or Deferred (which are not A/B/C/U grades), and only the two Trovi rows embed U in their disposition. Because this promise expressly includes entries that could not be verified, readers are still told every candidate has a grade when several do not; either add an explicit grade field there or narrow the guarantee to the sections where the rubric applies.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 795ff8c, by narrowing the guarantee rather than adding grades.
Grading a refuted candidate would be a category error: the A/B/C/U rubric measures how well a source supports an entry that belongs in the census, and nothing in Section 6 does. Assigning RAC a grade would imply it's an adopter with weak evidence, when the actual finding is that its full text never mentions libCacheSim.
So the header now scopes the grade promise to Sections 2–5 and says Section 6 is different by design, and Section 6 carries a defined disposition vocabulary instead:
| Disposition | Meaning |
|---|---|
| Excluded | Checked and refuted; the source does not support the claim |
| Unverified | Could not be checked at all; neither confirmed nor refuted |
| Deferred | Blocked by the snapshot environment, not by the source |
| Substituted | Primary unreachable; an equivalent source was used |
You also caught a vocabulary collision I'd left in: the two Trovi rows used a bare U in the disposition column, mixing grade letters with disposition words. They're now Unverified. The Excluded/Unverified distinction is worth having on its own — "refuted" and "couldn't check" are very different signals for whoever picks up the next revision.
Generated by Claude Code
| | 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. | |
There was a problem hiding this comment.
The v1.0.0 summary reports six distribution signals, but that version's Section 2 already contains seven data rows: stars, forks, PyPI package, PyPI maintainers, npm package, Python binding repository, and dependency-graph dependents. This leaves the census's compact baseline inventory inconsistent with its detailed table, so the count should be changed to seven.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed and corrected in 795ff8c. I counted the rows rather than taking it on faith — stars, forks, PyPI package, PyPI maintainers, npm package, Python binding repository, dependency-graph dependents — seven, as you say. The changelog said six.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 795ff8c077
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **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. |
There was a problem hiding this comment.
Section 6 also contains the two Unverified Trovi leads, a Deferred statistics task, and a Substituted source, all of which are unresolved or explicitly intended for later retry. Calling the entire section “investigated and rejected” and saying its entries should not be reinvestigated can cause maintainers to skip the priority follow-up work listed later in the document; reserve that description for the Excluded rows or describe the section more generally as checked candidates.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Good catch — the wording could have caused real harm, not just imprecision. Fixed in a1fc7bd.
"Investigated and rejected" is true of the two Excluded papers only. The Trovi leads are Unverified (never checked, because the pages are client-rendered) and the PyPI statistics are Deferred (blocked by an HTTP 429, not by the source) — both are explicitly on the next-revision priority list. Telling a maintainer not to re-investigate the section would have steered them away from the exact work the document asks for two sections later.
The header now says candidates that were checked but did not enter the census, marks only Excluded as settled, and links Unverified and Deferred straight to the priorities. That distinction is the reason the disposition vocabulary earns its keep: "refuted" and "couldn't check" imply opposite next actions.
Generated by Claude Code
| adoption of algorithms designed in it. Every entry carries its evidence, source URL, verification | ||
| date, and confidence grade. |
There was a problem hiding this comment.
After the Section 6 fix, the fresh remaining inconsistency is this README guarantee: the census now deliberately gives Section 6 entries dispositions rather than confidence grades. Readers entering through the project README are therefore still promised a grade for entries such as the deferred PyPI task and the unverified Trovi artifacts; scope this sentence to Sections 2–5 or mention the disposition exception.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in a1fc7bd — the README carried the unscoped version of the same promise the census header just corrected.
It now reads: 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.
That keeps the README's summary honest without dragging the full grade-versus-disposition rubric into it — a reader who wants the detail follows the link.
Generated by Claude Code
| 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. |
There was a problem hiding this comment.
Section 2's seven rows record measured values and source links, but none supplies a verbatim quotation, so including Section 2 in the guarantee that every entry carries “quoted evidence” overstates what the census contains. This also conflicts with the update checklist's verbatim-quote requirement for new Section 2 measurements; describe those rows as carrying a measured value instead, or add the promised quotations.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, and it was internally inconsistent too — the update checklist asked for "a verbatim quote … the measured value for Section 2", which is a contradiction in one sentence. Fixed in a1fc7bd.
The promise now names what each section actually carries: 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. Rule 2 of the update checklist says the same, asking Section 2 entries for the value plus the page it was read from.
I went this way rather than adding quotations because a manufactured quote around "339" would be ceremony, not evidence — the auditable facts for that row are the number, the source page, and the date.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a1fc7bd7f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### 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 |
There was a problem hiding this comment.
The link is labeled v1 but points to the unversioned /abs/2605.01055 endpoint, and unlike the other arXiv entries there is no versioned full-text link attached to the quoted evidence. If arXiv publishes a later revision, this Grade A source can silently show different text from the snapshot; link the artifact/evidence to the explicit v1 abstract or full text.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 3eb26f6 — and the same exposure existed on three other links, so I swept them all.
- SCION →
/abs/2605.01055v1 - PolicySmith →
/abs/2510.08803v1 - DynamicAdaptiveClimb →
/abs/2511.21235v1 - 2DIO →
/pdf/2603.19971v1
Each is pinned to the version I actually read, not just labelled with one.
The RAC row is the honest exception: I didn't record which version I fetched, so rather than assume v1 the row now says the check was against the version current on the date, version unrecorded. That matters more in Section 6 than elsewhere — the section explicitly warns that a paper not mentioning libCacheSim in one version may cite it in a later one, so an unpinned exclusion is exactly the kind of claim that quietly goes stale.
Generated by Claude Code
|
|
||
| | Grade | Meaning | | ||
| | --- | --- | | ||
| | **A** | Primary source, quoted verbatim, establishes the relationship claimed by that section unambiguously. | |
There was a problem hiding this comment.
After the new Section 2 carve-out, this rubric still defines every A as evidence that was “quoted verbatim,” while all seven Section 2 rows receive A based only on measured values and lines 49–51 explicitly say that is sufficient. The grade definition therefore still declares those rows ineligible for the grade assigned to them; make the quotation requirement conditional on the section's evidence type.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 3eb26f6. The definition now reads: 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).
You're right that it was self-refuting as written: the carve-out three lines below said a measured value earns an A, while the rubric line said only quoted evidence could. Making the quotation requirement conditional on the evidence type fixes it without adding a second grade scale.
Generated by Claude Code
| 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. |
There was a problem hiding this comment.
The revised guarantee now carves out Section 2 but still promises a verbatim quote for every Section 3–5 entry. The Pelikan and SkiftOS rows in Section 5.2 deliberately have no substantiating source text—the former links only a repository root and the latter is a 404—so neither carries the promised quote; scope this guarantee to substantiated entries or describe U-row evidence separately.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, and it's the one case where the missing quote is the point. Fixed in 3eb26f6.
The header now carves out Grade U explicitly: those rows have no substantiating quote because the absence of one is the finding. Pelikan's link resolves to a repository root with no implementing file; SkiftOS's returns 404. Manufacturing a quote for either would erase exactly what the row exists to record.
That completes the promise's shape — a verbatim quote in Sections 3–5, a measured value in Section 2, a documented absence for Grade U, and a disposition in Section 6.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3eb26f674d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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 |
There was a problem hiding this comment.
This description still includes the two Trovi leads even though rows 326–327 mark them Unverified, which the final tree explicitly defines as “Could not be checked at all.” Calling every Section 6 candidate checked overstates the snapshot's verification coverage; describe the section as containing investigated or unresolved candidates instead. The fresh evidence after the earlier wording fix is the new disposition definition at line 318, which directly contradicts this sentence.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Right — "checked" and "could not be checked at all" can't both be true of the same rows. Fixed in 708dd96.
Section 6 now holds candidates that were investigated but did not enter the census: some refuted, some never reachable at all. "Investigated" covers an attempt that failed, which is exactly what the two Trovi rows are.
I also tightened the column's meaning in the same pass, since it had the same problem in miniature: Date checked is now stated to be when the check was made or attempted. For an Unverified row, the date records when someone last tried and hit a client-rendered page — still useful, but not the same claim as having read the source.
Generated by Claude Code
| 4. Move anything that fails re-verification into [Section 6](#6-checked-and-excluded) with the | ||
| reason, rather than deleting it. |
There was a problem hiding this comment.
When a source fails re-verification, this rule unconditionally moves it to Section 6, but the current SkiftOS 404 is exactly such a failure and is deliberately retained in Section 5.2 as a Grade U lead. A maintainer following the checklist would therefore undo the document's stated U-row policy; limit this move to previously substantiated entries that no longer support the relationship, or explicitly say where Grade U leads belong.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
This one had teeth — the checklist would have told a maintainer to undo a deliberate decision. Fixed in 708dd96.
Rule 4 now splits by failure mode instead of moving everything:
- Refuted (source reachable, doesn't support the claim) → move to Section 6 as Excluded.
- Unreachable (404, paywall, withdrawn) → downgrade to Grade U in place and record what failed, when the entry sits in a named list where its absence is informative. Move to Section 6 only when the candidate has no place in a census table to begin with.
SkiftOS is named as the worked example, since the reasoning isn't obvious from the rule alone: the 404 is evidence that a published adopters list has rotted, and filing it under "checked and excluded" would bury that. Never delete under either branch.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
The previous edit left three em-dashes in one sentence. No change in meaning. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a04817130a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| --- | ||
|
|
||
| ## 6. Checked and excluded |
There was a problem hiding this comment.
The fresh remaining text after the earlier wording fix is the section heading itself: it still labels the entire section “Checked and excluded,” although the table includes two Unverified candidates that line 323 defines as never checked, plus Deferred and Substituted rows that are not excluded. A maintainer navigating by headings could therefore mistake the section for settled dead ends and skip the open follow-up work; use a neutral heading such as “Investigated candidates.”
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 5940bef — renamed to "6. Investigated candidates".
The heading was the last place the old framing survived after the body was corrected twice, and it's the part most likely to mislead: two of the six rows were never checked, and three aren't excluded. Someone scanning the table of contents would reasonably write the whole section off as settled dead ends, which is precisely the skip you flagged.
"Investigated" covers all four dispositions — refuted, unreachable, deferred, substituted — without asserting an outcome the rows don't share.
I also updated the internal anchors and verified that every ](#...) link in the document still resolves to a real heading, so the rename didn't leave dangling references.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5940bef75e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 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. |
There was a problem hiding this comment.
The fresh evidence after the earlier README wording change is the finalized Section 6 vocabulary: Unverified explicitly means “Could not be checked at all,” and the two Trovi rows have that disposition (doc/adoption-census.md lines 323 and 331–332). Describing all disposition-bearing candidates here as “checked” therefore still overstates the census's verification coverage; use “investigated” or otherwise include candidates whose checks could not be completed.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in e15b82c — the README now says "investigated but did not qualify", matching the Section 6 vocabulary.
Generated by Claude Code
| | 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. | |
There was a problem hiding this comment.
The fresh remaining instance after the earlier pinning fix is this v1.0.5 changelog entry: it says every GitHub link in Section 5.2 was pinned, but Pelikan still used a repository-root URL and SkiftOS still used blob/main in that revision, just as the current rows and limitation 5 acknowledge. Because this changelog is intended to audit exactly what each census revision established, scope the statement to the Grade A GitHub evidence links rather than preserving the false all-links claim.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Correct, and it matters more in the changelog than it would elsewhere. Fixed in e15b82c.
The v1.0.5 entry now reads: every GitHub link backing a Grade A row in Section 5.2 is pinned; the two Grade U rows stay unpinned by design and the PostgREST docs URL remains mutable.
The distinction you're drawing is the right one — the changelog audits what each revision established, so an overstated entry there misrepresents the historical record, not just the current state. Someone reading back through the versions to see when pinning landed would have concluded v1.0.5 closed something it didn't.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e15b82c93d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | 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. | |
There was a problem hiding this comment.
Section 6 contains two Excluded rows, two Unverified rows, one Deferred row, and one Substituted row, so four—not three—are not excluded. Because this changelog is intended to audit what each revision established, the incorrect count omits the Substituted row and leaves the v1.0.12 history inaccurate.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed by counting the table — two Excluded, two Unverified, one Deferred, one Substituted, so four of six. Fixed in 939052f.
Generated by Claude Code
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W7pawpqGUA7tKoaQQ3beMi
What this adds
doc/adoption-census.md— a versioned, source-linked inventory of documented libCacheSim adoption. Because it lives in the source tree, any commit of the file is a citable snapshot; the document carries a census version (1.0.0), a snapshot date (2026-08-12), and a citation block.Every entry records the artifact, a verbatim quote showing libCacheSim use, a source URL, the date the source was fetched, and a confidence grade (A/B/C/U).
Census v1.0.0 contents
Confirmed direct users (5) — public artifacts that build on, fork, or run libCacheSim, not merely cite it:
Also included: distribution and repository signals (GitHub stars/forks, PyPI
libcachesim, npmlibcachesim-node); self-reported aggregate claims, attributed and graded rather than asserted as fact; algorithm-lineage adoption of S3-FIFO/SIEVE with ten per-file evidence links; and a list of candidates checked and excluded.Design decisions worth reviewing
Other changes
Linked the census from
README.md(new "Who uses libCacheSim" section) and from thedoc/README.mdindex.No code changes; documentation only.
Generated by Claude Code