docs: MAE has no garbage collector — stop claiming one in three places - #679
Merged
Conversation
CLAUDE.md principle #1 said we use "a purpose-designed concurrent GC for the Scheme runtime". We do not, and nothing like it is built. Verified against the tree: * the Scheme heap is `Rc<T>` refcounted with NO tracing collector (`crates/scheme/src/value.rs`, "Stage 1"). A `Trace` trait exists as groundwork; nothing walks it. * `collections_count` is declared (`vm.rs:214`), copied to the editor (`runtime.rs:944`), and reported by `(gc-stats)`, `gc_stats_alist` and the `introspect` MCP tool — but NOTHING increments it. Every write to the field was checked. `(gc-stats)`'s `collections` is permanently 0. * `(gc-collect!)` is a no-op whose own doc string said it "increments counter in Rc stage", and whose body comment said "the VM increments gc_stats.collections_count when this runs". Neither was ever true. So the same false claim sat in three places: the file that primes every AI session, a registered Scheme doc string a user can call up, and the comment a maintainer would read before touching it. All three now describe Stage 1 as it is. Principle #1 additionally spells out what the reader must not be misled about: `Rc` is `!Send`, so the runtime is single-threaded by construction and "no GIL, ever" — while true — is vacuous today, since there is no shared multi-threaded interpreter for a lock to guard. Refcounting also leaks reference cycles, and `code_pool` is append-only. No test pins this. A test asserting `collections == 0` would obstruct the collector we actually want someone to build; the `@ai-caution: [docs-drift]` marker at the site carries the warning instead, including the specific wrong fix — incrementing the counter to match the docs. A counter that rises without a collection is a worse lie than one that stays at zero, because it reads as evidence that collection is happening. Amended in the open per principle #17, which asks for exactly this rather than letting an aspirational claim stand in the present tense. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
CLAUDE.md principle #1 said we use "a purpose-designed concurrent GC for the
Scheme runtime". We do not, and nothing like it is built.
Verified against the tree
Rc<T>refcounted with no tracing collector(
crates/scheme/src/value.rs, "Stage 1"). ATracetrait exists asgroundwork; nothing walks it.
collections_countis declared (vm.rs:214), copied to the editor(
runtime.rs:944), and reported by(gc-stats),gc_stats_alistand theintrospectMCP tool — but nothing increments it. Every write to the fieldwas checked.
(gc-stats)'scollectionsis permanently0.(gc-collect!)is a no-op whose own doc string said it "increments counter inRc stage", and whose body comment said "the VM increments
gc_stats.collections_count when this runs". Neither was ever true.
Why three places matter
The same false claim sat in the file that primes every AI session, in a
registered Scheme doc string any user can call up, and in the comment a
maintainer would read immediately before touching the code. Fixing one and
leaving the others would just relocate the misinformation.
Principle #1 now also spells out what a reader must not be misled about:
Rcis!Send, so the runtime is single-threaded by construction and "no GIL, ever" —while true — is vacuous at Stage 1, since there is no shared multi-threaded
interpreter for a lock to guard. Refcounting also leaks reference cycles, and
code_poolis append-only.Deliberately no test
A test asserting
collections == 0would pin a no-op and obstruct the collectorwe actually want someone to build. The
@ai-caution: [docs-drift]marker at thesite carries the warning instead — including the specific wrong fix, which is
incrementing the counter to match the docs. A counter that rises without a
collection is a worse lie than one that stays at zero, because it reads as
evidence that collection is happening.
Amended in the open per principle #17, which asks for exactly this rather than
letting an aspirational claim stand in the present tense.
No overlap with any PR currently open.
🤖 Generated with Claude Code