docs: two claims that were asserted rather than checked - #25
Merged
Merged
Conversation
Both are the same defect the 0.1.2 CHANGELOG is itself about, which is why they are worth fixing rather than leaving. 1. The four CHANGELOGs' 0.1.2 entry ended: "What remains naming it is the handful of places where the two-repository split is the actual subject — the README, SECURITY.md, and docs/reference/README.md." Twenty-one tracked files name the core repository, all of them legitimately. The enumeration was never checked and undercounts by eighteen. The entry immediately above it is the one explaining that a sweep reported itself complete while 148 of its targets survived, and that the fix which outlives that is a rule a linter can enforce. Then it enumerated a file list. Replaced with the rule — describing the split is legal, naming something a reader cannot open is not, and scripts/lint-public.sh is what decides — plus a note saying what the old count got wrong, because this entry has now been wrong once and silently correcting it would repeat the original mistake. All four CHANGELOGs are edited identically; they are released together and tell one story. This already shipped inside 0.1.2 on all four registries. A repository is not a registry: the correction reaches npm, PyPI, crates.io and the Go proxy at the next release, not before. 2. docs/reference/artifact.md said "A loader SHOULD verify the hash before dlopen ... and MUST when it came from a network", with no indication that half the reference bindings do not. Measured: Python has verify_hashes and TypeScript has verifyChecksums; go/chtypes/multiversion.go has no hash path at all, and rust/src/registry.rs says in its own doc-comment that the crate does not hash because it takes no crypto dependency. A normative MUST that two of four implementations silently ignore is worse than no MUST: a reader assumes the guarantee. The requirement stands and now names who meets it, what the other two rely on instead, and what a caller must therefore do. Same treatment as the mandatory-symbol count in the same file, and the divergence is #13 A2, already filed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ckJDLjWhAAttQVrYnQEJD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Both are the same defect the 0.1.2 CHANGELOG is itself about, which is why they are worth fixing rather than leaving.
1. The CHANGELOG enumerated three files. Twenty-one qualify.
The 0.1.2 entry, in all four CHANGELOGs, ended:
Measured on
main, excluding generated fixtures:All of them legitimately — describing the split is exactly what
lint-public.shdeliberately permits. The problem is not the content, it is that the count was never checked and is wrong by eighteen.The paragraph immediately above it in the same entry is the one explaining that a sweep reported itself complete while 148 of its targets survived, and that the fix which outlives that is a rule a linter can enforce. And then it enumerated a file list.
Replaced with the rule — describing the split is legal, naming something a reader cannot open is not,
scripts/lint-public.shdecides — plus an explicit note of what the old count got wrong. Silently correcting it would repeat the original mistake: this entry has now been wrong once, and a reader who acted on the list deserves to know. All four CHANGELOGs edited identically; they are released together and tell one story.2. A normative MUST that half the bindings ignore
docs/reference/artifact.mdsaid:with no indication that half the reference bindings don't. Measured:
verify_hashesverifyChecksumsmultiversion.goat allregistry.rs— "This crate does not hash (it takes no crypto dependency)"A
MUSTthat two of four implementations silently ignore is worse than noMUST, because a reader assumes the guarantee is there. The requirement stands — it now names who meets it, what the other two rely on instead (the release pipeline's own verification), and what a caller pointing either at network-sourced bytes must therefore do themselves.Same treatment as the mandatory-symbol count in this file in #23: describe reality, do not quietly pick a winner. The divergence is #13 A2 and was already filed.
Verification
lint-prose,lint-public,markdownlint,dprint checkclean; parity 9/9 (it reads these docs). Prose lint caught a British "licence" in my own new sentence before it left the branch.🤖 Generated with Claude Code
https://claude.ai/code/session_018ckJDLjWhAAttQVrYnQEJD