Skip to content

docs: two claims that were asserted rather than checked - #25

Merged
EricAndrechek merged 1 commit into
mainfrom
docs-verification-claim
Sep 11, 2026
Merged

EricAndrechek merged 1 commit into
mainfrom
docs-verification-claim

Conversation

@EricAndrechek

Copy link
Copy Markdown
Member

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:

"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."

Measured on main, excluding generated fixtures:

21 tracked files name "core repository" / "core repo"

All of them legitimately — describing the split is exactly what lint-public.sh deliberately 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.sh decides — 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.

⚠️ This already shipped inside 0.1.2 on all four registries. A fixed repository is not a fixed registry — the correction reaches npm, PyPI, crates.io and the Go proxy at the next release, not before.

2. A normative MUST that half the bindings ignore

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 don't. Measured:

binding load-time hash verification
Python verify_hashes
TypeScript verifyChecksums
Go ❌ no hash path in multiversion.go at all
Rust registry.rs"This crate does not hash (it takes no crypto dependency)"

A MUST that two of four implementations silently ignore is worse than no MUST, 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 check clean; 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

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
@EricAndrechek
EricAndrechek merged commit b8dbd27 into main Sep 11, 2026
14 checks passed
@EricAndrechek
EricAndrechek deleted the docs-verification-claim branch September 11, 2026 18:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant