Skip to content

docs: MAE has no garbage collector — stop claiming one in three places - #679

Merged
cuttlefisch merged 2 commits into
mainfrom
fix/gc-claims-drift
Aug 7, 2026
Merged

docs: MAE has no garbage collector — stop claiming one in three places#679
cuttlefisch merged 2 commits into
mainfrom
fix/gc-claims-drift

Conversation

@cuttlefisch

Copy link
Copy Markdown
Owner

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.

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: Rc is
!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_pool is append-only.

Deliberately no test

A test asserting collections == 0 would pin a no-op and 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, 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

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>
@cuttlefisch cuttlefisch added the release:none Skip version bump on merge label Aug 6, 2026
@cuttlefisch
cuttlefisch merged commit 94323d2 into main Aug 7, 2026
23 checks passed
@cuttlefisch
cuttlefisch deleted the fix/gc-claims-drift branch August 7, 2026 08:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release:none Skip version bump on merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant