Skip to content

vm: derive the open doors instead of listing them, and wire the fourth - #951

Merged
tannevaled merged 2 commits into
mainfrom
open-doors-ratchet
Nov 16, 2026
Merged

tannevaled merged 2 commits into
mainfrom
open-doors-ratchet

Conversation

@tannevaled

@tannevaled tannevaled commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Klass.open { |x| … } in Ruby yields, closes however the block leaves, and
answers with the block's value. Writing smethods["open"] = smethods["new"]
gives none of that: new has no block parameter, so the block is discarded in
silence and the call still looks like it worked. That one line cost #916 its 27
hung library/net-http files — the fixture shuts its server down from inside
TCPSocket.open { … }, and with the socket still open the server's gets never
returns.

⛔ The list of doors is what kept drifting

A hand-written list of doors is the same artefact as any other hand-written list,
so TestEveryOpenDoorIsAccountedFor holds none. It parses the package with
go/ast, on every platform (go/parser ignores build tags — which is how the
windows-only UNIX doors get counted, and the prose list missed UNIXServer in
exactly such a file), finds all 18 smethods["open"] assignments, and
compares them to testdata/open-doors.txt both ways: a door missing from the
table fails, and a row for a door that no longer exists fails too.

The alias form is refused outright, with no table entry possible, because no
configuration of it can be correct.

The controls, because a gate that cannot go red is a decoration

control what it would catch
mutation: put the alias back prints ⛔ 1 open door(s) are an ALIAS … resolv.go:dns, naming file and receiver
TestTheOpenDoorClassifierTellsTheShapesApart a classifier that answered "block helper" for everything — every assertion above would pass against it
the same test's negative half a matcher that also fired on smethods["new"] or methods["open"], which could meet the population floor with noise
len(doors) < 15 a derivation that silently matches nothing and reports a clean package

The fourth door, measured against MRI 4.0.7

MRI 4.0.7 rbgo (before)
Resolv::DNS.open { |dns| :from_block } yields, returns :from_block does not yield, returns the resolver
Resolv::DNS#close nil NotImplementedError
a second close fine NotImplementedError
close("x") ArgumentError: wrong number of arguments (given 1, expected 0) NotImplementedError
method(:close).arity 0 -1

Both halves are one fix: socketOpenWithBlock closes through the class's own
#close, so leaving #close on the NotImplementedError list would have turned
every Resolv::DNS.open { … } into a NotImplementedError raised from the
ensure — a block that now runs, and a program that now fails. Same trap as #948's
teardown flush, one hour apart.

rubydiff against MRI 4.0.7 now AGREES on both witnesses — stdout, stderr
and exit status — where it diverged on three rows before.

⛔ A pre-existing test that was right for the wrong reason

TestResolvDNS asserted that Resolv::DNS.new.close("x") raises, and it did —
with NotImplementedError, because the stub raised for every call. So the
test could not tell "close rejects an argument" from "close does nothing at
all"
, and a no-op close turned it red. That is the test finally asking its own
question. close comes off that loop's hand-written list — which mirrored the
production one, so the two could only drift together — and is asserted on its
message and its arity instead.

defineArgc declares the 0 for #arity/#parameters/#inspect but by design
does not enforce it, so the count is checked in the body too.

What the derivation exposed and leaves open — see #950, which this does NOT resolve

Two doors take a block and discard it: Augeas.open (augeas.go:71, shared
with Augeas.create) and Images::Image.open (images.go:93), both _ *Proc.
The other seven inline handlers were read one by one in the same pass and all
honour theirs (File, IO, StringIO, Dir, Net::FTP,
SQLite3::Database, bbolt).

The references were then read, and the two are not in the same state:

  • Augeas.open is a confirmed defect. ruby-augeas's lib/augeas.rb defines
    def self.open(root = nil, loadpath = nil, flags = NONE, &block), which under
    block_given? does rv = yield aug; return rv with ensure aug.close —
    exactly socketOpenWithBlock's contract, same parameters and all. It is not
    fixed here
    because it is two parts: rbgo's Augeas has no #close at
    all
    (git grep close internal/vm/augeas.go is empty), so the helper would
    yield without closing and aug.close in Ruby is a NoMethodError. Adding
    #close means reading go-augeas's handle API, which is its own change.
  • Images::Image.open is unspecified, not a known defect. go-ruby-images'
    README documents no Ruby Image.open and no block form at all — it documents
    the Go library (images.Open("photo.jpg")) — and ruby-vips and MiniMagick
    spell this operation without a block. "No block form" may be the contract to
    document rather than a gap to fill.

Both stay in the table with that distinction written down, so two doors are
countable rather than quiet, and #950 carries what settles the second.

⚠ There is no issue to close for the fourth door

"#939 filed it" — which its own text and the recurrence ledger both say — meant
recorded in prose, inside a merged pull request. gh issue list --search "Resolv in:title" over every state answers []. A door named only in a merged
PR body is as findable as one named nowhere, which is the same lesson as the prose
list that led to it.

Refs #931, #916, #939, #950, #948

🤖 Generated with Claude Code

tannevaled and others added 2 commits November 15, 2026 22:54
`Klass.open { |x| … }` yields, closes however the block leaves, and
answers with the BLOCK's value. `smethods["open"] = smethods["new"]`
gives none of that — `new` has no block parameter, so the block is
discarded in silence and the call still looks like it worked. That one
line cost #916 its 27 hung library/net-http files.

⛔ AND THE LIST OF DOORS IS WHAT KEPT DRIFTING. #931 wrote the socket
doors out in prose and the prose had already lost UNIXServer; #939
re-derived them from the source, fixed three, and found a FOURTH nobody
had written down — Resolv::DNS, outside the socket family — which it
filed rather than fixed. A hand-written list of doors is the same
artefact as any other hand-written list.

So TestEveryOpenDoorIsAccountedFor holds none. It parses the package with
go/ast, on EVERY platform (go/parser ignores build tags, which is how the
windows-only UNIX doors get counted — the prose list missed UNIXServer in
exactly such a file), finds all 18 `smethods["open"]` assignments, and
compares them to testdata/open-doors.txt BOTH WAYS: a door missing from
the table fails, and a row for a door that no longer exists fails too.

The ALIAS form is refused outright, because no configuration of it can be
correct. Mutation control: putting the alias back prints
`⛔ 1 open door(s) are an ALIAS … resolv.go:dns`, naming file and
receiver. TestTheOpenDoorClassifierTellsTheShapesApart feeds the four
shapes to the classifier directly — without it every assertion would
pass against a classifier that answered "block helper" for everything.

## The fourth door, measured against MRI 4.0.7

    Resolv::DNS.open { |dns| :from_block }
      MRI   yields, returns :from_block
      rbgo  did NOT yield, returned #<Resolv::DNS…>
    Resolv::DNS#close
      MRI   nil, and a second close is fine
      rbgo  NotImplementedError, both times

Both halves are ONE fix: socketOpenWithBlock closes through the class's
own #close, so leaving #close on the NotImplementedError list would have
turned every `Resolv::DNS.open { … }` into a NotImplementedError raised
from the ensure — a block that now runs, and a program that now fails.
Same trap as #948's teardown flush.

⛔ And #close takes NO arguments. The pre-existing TestResolvDNS asserted
that `close("x")` raises, and it did — with NotImplementedError, which is
the right verdict for the wrong reason: the stub raised for every call,
so the test could not tell "close rejects an argument" from "close does
nothing at all". A no-op close turned it red, which is the test finally
asking its own question. MRI 4.0.7: ArgumentError "wrong number of
arguments (given 1, expected 0)", arity 0, `close` → nil. `close` comes
off that loop's hand-written list (which mirrored the production one) and
is asserted on its MESSAGE and its arity instead.

rubydiff against MRI 4.0.7 now AGREES on both witnesses — stdout, stderr
and exit status — where it diverged on three rows before.

## What the derivation exposed: #950

Two doors take a block and discard it: Augeas.open (augeas.go:71, shared
with Augeas.create) and Images::Image.open (images.go:93), both `_ *Proc`.
The other seven inline handlers were read one by one and all honour
theirs (File, IO, StringIO, Dir, Net::FTP, SQLite3::Database, bbolt).

NOT measured, and it is the whole decision: whether the reference gems
accept a block at all. Neither is installed here. Images::Image.open may
be CORRECT — ruby-vips and MiniMagick spell this without a block. Listed
in the table as unverified, with #950 carrying the command that settles
it, so two doors are countable rather than quiet.

⚠ There is no issue to close for the fourth door. "#939 filed it" — which
is what its own text and the recurrence ledger both say — meant RECORDED
IN PROSE, inside #939: `gh issue list --search "Resolv in:title"` over
every state answers `[]`. A door named only in a merged pull request's
body is as findable as one named nowhere, which is the same lesson as the
prose list it was found by.

Refs #931, #916, #939, #950, #948

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…lled'

The table said ruby-augeas is 'BELIEVED to yield and close, but that is
recalled and not read'. It has now been read, so that sentence was the
exact shape it warns against — a dated claim left standing in a file
whose only job is to be honest about what is verified.

ruby-augeas lib/augeas.rb:

    def self.open(root = nil, loadpath = nil, flags = NONE, &block)
        aug = open3(root, loadpath, flags)
        if block_given?
            begin
                rv = yield aug
                return rv
            ensure
                aug.close
            end
        else
            return aug
        end
    end

Same parameters as rbgo's, and exactly socketOpenWithBlock's contract.
So Augeas.open is a CONFIRMED defect, not an open question.

Still not fixed here, and the reason is new: rbgo's Augeas has no #close
AT ALL (git grep close internal/vm/augeas.go is empty), so the helper
would yield without closing and aug.close in Ruby is a NoMethodError.
Adding #close means reading go-augeas's handle API, which is its own
change.

Images::Image.open moves the other way: go-ruby-images' README documents
no Ruby Image.open and no block form at all, only the Go-level
images.Open(path). It is UNSPECIFIED, not a known defect, and the two
rows no longer read as if they were in the same state.

Refs #950

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@tannevaled
tannevaled merged commit 213d056 into main Nov 16, 2026
26 checks passed
@tannevaled
tannevaled deleted the open-doors-ratchet branch November 16, 2026 00:15
tannevaled added a commit that referenced this pull request Nov 16, 2026
* vm(augeas): #close, the block form, and create's real signature

#950's row in testdata/open-doors.txt said Augeas.open's discarded block
could not be fixed because "rbgo's Augeas has no #close method at all, so
the helper would yield without closing", and go-ruby-augeas's handle
exposes no Close either.

⛔ THAT WAS THE WRONG LAYER. The gem's #close frees a C handle, but what
it makes OBSERVABLE is two things, and neither needs anything from the
dependency:

    VALUE augeas_close (VALUE s) {
        augeas *aug = aug_handle(s);
        aug_close(aug);
        DATA_PTR(s) = NULL;
        return Qnil;
    }

    /* aug_handle, which EVERY method calls first */
    if (aug == NULL) {
        rb_raise(rb_eSystemCallError, "Failed to retrieve connection");
    }

It answers nil, and afterwards every method raises — including a second
#close, because aug_handle runs before aug_close. That is a flag plus a
guard. I asked what #close FREES; the question was what it makes
observable.

The guard goes in augeas_bind.go's `self` accessor, which all seventeen
instance methods already go through and nothing else does — the one-door
shape #951 had to derive with a parser because `open` had five.

Reading the reference properly also turned up a divergence nobody had
filed: `create` and `open` were THE SAME positional native, and in the
gem they are not the same function at all.

    lib/augeas.rb:  def self.open(root = nil, loadpath = nil, flags = NONE, &block)
    lib/augeas.rb:  def self.create(opts={}, &block)   -> Augeas::Facade::create

create takes an OPTIONS HASH. Three things about facade.rb's single
`opts.each_key` pass are reproduced because each is what a tidier
reimplementation gets wrong:

  - a flag is armed by its KEY'S PRESENCE, never its value, so
    create(type_check: false) sets TYPE_CHECK;
  - :root and :loadpath are excluded by the final elsif's own condition,
    not removed from the hash;
  - validation and assembly share ONE pass, so the FIRST offending key
    raises. create(save_mode: :bogus, nonsense: 1) says "Invalid save
    mode bogus." and the same two keys the other way round say "Unknown
    argument nonsense." Both orders are asserted, because agreeing with
    one of them is not agreeing with the gem.

⛔ BREAKING for this binding: Augeas.create("/root", "/lens", 5) was
accepted and is now a TypeError. Below v1 that is a MINOR bump.

⛔⛔ AND THE RATCHET I LANDED YESTERDAY WAS BLIND TO ITS OWN SUBJECT.
TestEveryOpenDoorIsAccountedFor marked every derived door `seen`,
block-helper ones included, then called a table row stale only when no
door carried its key. So it asked "does this door still exist?" when the
question is "does this door still NEED a row?". Augeas.open went from an
inline block-discarding handler to socketOpenWithBlock and the test
stayed GREEN with the row still reading "⛔ CONFIRMED DEFECT" about it: a
gate that cannot see the repair it exists to ask for goes on publishing a
defect that is gone — the same artefact #931's prose was, in the other
direction.

It was not found by re-reading the test. It was found by changing the
code the gate watches and noticing THE GATE DID NOT MOVE. The verdict is
now compareOpenDoors, a pure function with its own control
(TestTheDoorTableComparisonFailsInBothDirections, 7 cases) because the
live package can only ever show the comparison AGREEING. Confirmed by
hand too: re-adding the row makes the live test red and names the fix.

Measured, not recalled:

  - the gem's lib/augeas.rb, lib/augeas/facade.rb and
    ext/augeas/_augeas.c were READ. There is no oracle to run here: the
    augeas gem is a C extension over libaugeas and is not installed, so
    the reference is the source, quoted in the code.
  - TestEveryMethodOfAClosedAugeasRaises derives the method population
    from Augeas.instance_methods(false) (18) rather than listing it, so a
    method added later that reaches the handle another way is in the test
    the day it exists.
  - the flag arithmetic is asserted as NUMBERS, not re-derived from the
    constants the code uses. It earned that immediately: [2, 8, 16] was
    written from memory for the three save modes, the test went red, and
    the source settled it against the test — SaveBackup 1<<0,
    SaveNewFile 1<<1, SaveNoop 1<<4, which is augeas.h's AUG_* order.
  - gofmt clean; buildscan --vet: "go vet passed under all 19".

Refs #950, #951, #931

#950 stays OPEN: this is its Augeas half. Images::Image.open still
discards its block, and that half is not a known defect — go-ruby-images
documents no Ruby Image.open and no block form at all, so what it needs
is a reference, not a patch. #951 is merged; it is named here because its
ratchet is what this change repairs. #931 is untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test(augeas): cover open's own arity guard, which the ratchet caught

CI: `internal/vm/augeas.go registerAugeas 94.4% (was fully covered)`.
The uncovered branch is Augeas.open's arity guard — the gem's open takes
three positional arguments, a fourth is an ArgumentError, and I wrote
the guard and never executed it. create's two-argument case was tested;
open's four-argument case was not, and they are different functions now.

⛔⛔ SECOND TIME IN ONE SESSION. #948 came back on
`flushOneAtTeardown 83.3%`; this is `registerAugeas 94.4%`. 49 and 64
minutes of CI for a branch I had just written.

And it is neither a missing tool nor a missing note.
scripts/coverage/README.md gives the exact recipe — `covratchet -profile
<x>.func -require <names>`, which REFUSES a name that matched nothing
and prints its denominator — and states its own reason for existing:

    It exists because the ratchet, correct as it is, only refuses AFTER
    the spend. […] A gate that refuses after the spend teaches the
    lesson; one that refuses before it prevents the mistake.

I ran gofmt, `buildscan --vet` and the full suite. NONE of the three
answers "are the functions this commit claims to cover actually at
100%". Taken now, before pushing:

    required 7 function(s), matched 7 record(s) in a profile of 7627
    all required functions at 100%

(registerAugeas, registerAugeasMethods, augCreateOpts, augInterp, plus
#948's trackOpenFile, flushOpenFiles, flushOneAtTeardown.)

⛔ Two things that measurement taught, both worth writing down:

  - `-require compareOpenDoors` matched NOTHING and the tool refused
    rather than reporting clean. Correct: it is defined in a _test.go
    file, so it is not in any profile. My -require list was wrong, not
    the code — which is the failure mode the tool was built to name.
  - the FULL `-record` comparison against BELOW100.macos-latest reported
    87 functions "newly below 100%" from this profile. That is not a
    finding: the profile is `./internal/vm/` only, while the record is
    kept by a lane running `./...`, so compiler and bytecode coverage is
    absent by construction. Judge and subject must count alike. For a
    selective profile the `-require` form is the valid question, exactly
    as that README says.

Refs #948, #950

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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