Skip to content

vm(augeas): #close, the block form, and create's real signature - #952

Merged
tannevaled merged 2 commits into
mainfrom
augeas-close-and-create
Nov 16, 2026
Merged

tannevaled merged 2 commits into
mainfrom
augeas-close-and-create

Conversation

@tannevaled

Copy link
Copy Markdown
Contributor

The blocker was in the wrong layer

#950 says Augeas.open discards its block, and the row I wrote for it in testdata/open-doors.txt said the fix was blocked:

NOT fixed here because it is TWO parts: rbgo's Augeas has no #close method at all, so the helper would yield without closing and aug.close in Ruby is a NoMethodError.

Literally true — and go-ruby-augeas's handle exposes no Close either (18 exported methods, none of them it). So I filed it as blocked.

I asked what #close frees. The question is what it makes observable. From ext/augeas/_augeas.c, read for this change:

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 everything raises — a second #close included, because aug_handle runs before aug_close. In an in-memory tree there is nothing to free, so the flag is the whole mechanism, and the guard goes at the one door all seventeen instance methods already pass through (self in augeas_bind.go). Nothing was needed from the dependency.

While reading the reference, a third divergence nobody had filed

create and open were the same positional native. In the gem they are not the same function:

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

Augeas.create takes an options hash. Three properties of facade.rb's single opts.each_key pass are reproduced on purpose, because each is what a tidier reimplementation gets wrong:

A flag is armed by its key's presence, never its value (flags.key? key) so create(type_check: false) sets TYPE_CHECK
:root / :loadpath are excluded by the final elsif's own condition the hash is never mutated
Validation and assembly share one pass the first offending key raises, so the error depends on the caller's insertion order

That last one is asserted both ways round, because agreeing with one order is not agreeing with the gem:

Augeas.create(save_mode: :bogus, nonsense: 1)  # ArgumentError: Invalid save mode bogus.
Augeas.create(nonsense: 1, save_mode: :bogus)  # ArgumentError: Unknown argument nonsense.

⛔ 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 (#951, merged ~24h ago) marked every derived door seen, socketOpenWithBlock 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, one of them "a door FIXED into socketOpenWithBlock leaves its row stale" — because the live package can only ever show the comparison agreeing, never show it wrong. Confirmed by hand as well: re-adding the row turns the live test red and the message names the fix.

Measured, not recalled

  • There is no oracle to run. The augeas gem is a C extension over libaugeas and is not installed (gem list augeas is empty under Ruby 4.0.7), so the reference is the source — lib/augeas.rb, lib/augeas/facade.rb, ext/augeas/_augeas.c, all read, all quoted in the code next to what they justify.
  • TestEveryMethodOfAClosedAugeasRaises derives the population from Augeas.instance_methods(false) (18) instead of listing it, so a method added later that reaches the handle some other way is in the test the day it exists. It asserts the weakest true thing — no method of a closed handle succeeds — because arity is checked before the handle, which is also the gem's order.
  • The flag arithmetic is asserted as numbers, not re-derived from the constants the code uses, and it earned that on its first run: [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 — augeas.h's AUG_* order). Re-deriving them would have agreed with a wrong binding in silence.
  • gofmt -l . prints nothing; buildscan --dir . --vet → "go vet passed under all 19"; full ./internal/vm/ suite green.
  • README, landing and docs site: checked and need nothing. Augeas appears in this repository only in the README's gem list (README.md:70), and nowhere at all in go-embedded-ruby.github.io or the docs site — no page states the old signature, and this change makes the binding less divergent, so there is no row to add.

Dispositions

Refs #950, #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 and named only because its ratchet is what this repairs. #931 is untouched.

🤖 Generated with Claude Code

#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>
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>
@tannevaled
tannevaled merged commit 96a8905 into main Nov 16, 2026
26 checks passed
@tannevaled
tannevaled deleted the augeas-close-and-create branch November 16, 2026 03:20
tannevaled added a commit that referenced this pull request Nov 17, 2026
…lter (#958)

#950's second half asked whether Images::Image.open discarding its block
is a gap, the way the socket doors' discarded blocks were (#931/#932: 27
hung spec files) and Augeas.open's was (#952). The row in
testdata/open-doors.txt said "UNSPECIFIED, not a known defect" because
nobody had read the reference.

Read now. go-ruby-images' README calls itself "a MiniMagick / ruby-vips
replacement", and MiniMagick's lib/mini_magick/image.rb declares:

    def self.open(path_or_url, ext = nil, **options)

with NO block parameter — no `yield`, no `block_given?`, no `ensure`.
The only blocks in its body are internal, handed to `uri.open` and
`pathname.open`. ruby-vips has no `Image.open` at all; it spells this
`Vips::Image.new_from_file`. A Ruby method that takes no block and is
handed one ignores it, so rbgo is already right. Nothing to fix.

⛔⛔ AND THE "FIX" WOULD BE WORSE THAN POINTLESS. socketOpenWithBlock
closes through the CLASS'S OWN `close`, and on Images::Image `close` is
the MORPHOLOGICAL CLOSING operator — dilate then erode, taking a radius —
exactly as `#open` is morphological opening. Wrapping the door would run
an image filter on the way out of every block, believing it had released
something.

That is measured, not reasoned: wiring it makes the program die with

    ArgumentError: wrong number of arguments (given 0, expected 1)

raised by that operator, called with no radius from the helper's defer.

So three things land, none of them a behaviour change:

  - TestImagesImageOpenTakesNoBlock pins the contract. Without it the
    correct behaviour is INDISTINGUISHABLE from the defect it resembles:
    three other `open` doors that discarded a block were real bugs, so
    the next reader has every reason to assume a fourth. It asserts both
    halves a yield-only change would get wrong — the block does not run,
    and `open` answers the IMAGE, not the block's value.
  - the open-doors row is upgraded from UNSPECIFIED to reference-read,
    and says why the door STAYS listed: the row is what protects a
    correct door from being repaired.
  - socketOpenWithBlock's comment now states the assumption it was
    carrying silently — that `close` means "release" on the class being
    wrapped — with this counter-example. Nothing in the helper can tell
    the two meanings apart, since a native checks its own arguments and
    even arity is not introspectable; the door table is the check that
    can, so the instruction is to read what a new class's `close` does
    before wrapping it.

⛔ What I did NOT file, having looked: rbgo's `Image.open` takes one
argument where MiniMagick takes `(path_or_url, ext = nil, **options)`,
and `imagesArity` is a MINIMUM, so a second argument is silently ignored
rather than refused. That is cosmetic for decoding — go-ruby-images'
Open calls image.Decode, which SNIFFS the format from content via the
registered PNG/JPEG/GIF/BMP/TIFF/WebP decoders, so the `ext` hint changes
nothing either way. The URL half is a real gap (MiniMagick fetches
http/https/ftp) and is #957 rather than smuggled in here, because
implementing it gives the interpreter an outbound fetch driven by a
path-shaped argument — a judgement for the maintainer, not a parity
checkbox.

Verified by mutation, not by reading: wiring the door red-lines BOTH
gates independently — the behavioural test, and the ratchet, which
reports the row as one that no longer needs one. Reverted, both green.
gofmt clean, buildscan --vet under all 19.

Closes #950
Refs #957, #931, #932, #952

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