[tannevaled]

Corrects the embedding section of the README against what the code does, and adds the capability statement it was missing. Comes out of a security audit of rbgo; the behavioural half is tracked separately in #768.

Every number and quoted output below I measured myself, against origin/main (610a64a), through the public Run and nothing else — a four-line Go embedder, not the rbgo CLI, because cmd/rbgo configures things Run does not.

1. "Nothing is shared between calls" was true of the heap and false of the process

The bullet said, unqualified:

Every call is a fresh VM. A global set in one Run is gone in the next, and nothing is shared between calls.

Measured. A script that does nothing but touch process state:

ENV["VMARK"] = "set-inside-run"
Dir.chdir("/tmp")
ENV["PATH"] = "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/attacker/bin"

HOST-BEFORE cwd=/Users/Shared/rbgo-measure/w62/verify PATHlen=860 MARK=""
ruby: done
RUN-RETURNED err=<nil>
HOST-AFTER  cwd=/private/tmp PATHlen=13 MARK="set-inside-run"
HOST-ALIVE

The host Go process's working directory moved, its PATH went from 860 bytes to 13, and VMARK was set — and it all stayed that way after Run returned nil.

What makes this a documentation defect rather than a surprise is that the next bullet already said so:

require_relative resolves against the process working directory

So the README held the fact that contradicted its own claim, two lines apart. The two together are also a cross-call code path: one Run can write a file that a later Run loads.

The narrow reading does hold, and I checked it rather than assuming the whole bullet was wrong — a global, a constant and a String monkey-patch from call #1 are all absent in call #2. So the bullet is now scoped to the heap instead of being removed.

2. exit / exit! / abort report success

abort "fatal: tenant failed"  ->  RUN-RETURNED err=<nil>   (and "fatal: tenant failed" in out)
exit 3                        ->  RUN-RETURNED err=<nil>
exit!(42)                     ->  RUN-RETURNED err=<nil>
raise "boom"                  ->  RUN-RETURNED err=RuntimeError: boom

MRI exits 1 / 3 / 42 / 1. An embedder cannot distinguish "finished" from "stopped", and abort's message lands in out looking like ordinary output. The README documented only the raise case, which is the one that works. Now stated, with why it is not something an embedder can work around: cmd/rbgo/exit_status.go recovers the status through machine.TerminalExit(), but run.go discards the *vm.VM and internal/vm is unreachable from outside.

3. Kernel#fork exists, and does not fork

The README said only:

There is no Process.fork (Process.respond_to?(:fork) is false)

True, and it reads as "fork is unavailable". But fork { } — the spelling almost every program uses — exists:

$g = "parent-value"
pid = fork { $g = "CHILD-MUTATED-PARENT" }
Process.wait(pid) rescue nil
puts "after fork: $g=#{$g.inspect} pid_is=#{pid.inspect} mypid=#{Process.pid}"

rbgo: after fork: $g="CHILD-MUTATED-PARENT" pid_is=100001 mypid=26239
MRI : after fork: $g="parent-value"         pid_is=26244  mypid=26241

The "child" overwrote the parent's global and the pid is synthetic. internal/vm/spawn.go says so outright — "Without an OS fork we run the block in-process". Code that forks to isolate or to drop privileges gets neither, which is why this belongs in the divergence table rather than in a footnote.

4. A "Run is not a sandbox" subsection

Not a defect report: MRI is not sandboxed either, and conformance is the goal. It is worth saying because MRI is normally a CLI a person invokes on their own code, whereas Run is a function someone links into a server — and the README had no safety language at all (I searched for sandbox|untrusted|isolat|taint|$SAFE|secure; every hit was securerandom or the rbgo_closed build tag).

Measured through Run, with MRI side by side:

probe	rbgo	MRI
File.read("/etc/passwd")	returns it	same
Dir.glob("~/.ssh/*")	34 entries	34
File.symlink then read	works	works
TCPServer + TCPSocket round trip	"PONG"	"PONG"
require "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/abs/path.rb"	loads and executes	same
system / backticks / %x{} / IO.popen / Process.spawn	all spawn	same
IO.for_fd(1).write(...)	Errno::EBADF	writes to the real fd
defined?(RubyVM)	nil	"constant"
require "fiddle"	LoadError	loads
ObjectSpace.each_object	16	21169
ObjectSpace.each_object(String)	0	16167

Shell metacharacters go to /bin/sh -c (internal/vm/spawn_native.go, shellish), so pipes, ;, $(...), globs and redirection all work.

The last two columns are the reason the section also records what is deliberately out of reach: no RubyVM, ObjectSpace is effectively a stub, fiddle will not load, CGO is 0 — so there is no path from Ruby to the host's Go state — and the host's standard descriptors are not exposed. That IO.for_fd(1) raises EBADF where MRI writes to the real descriptor is a genuine property worth not losing by accident: a script cannot write outside the out the embedder passed.

I had drafted two further bullets (UDPSocket/Net::HTTP, and reading the host's own executable) from a second measurement that hung before returning, so I narrowed both claims to what I had actually seen rather than publish them. If the socket probe turns out to hang inside rbgo that is a finding of its own, and it will get its own issue.

Tests

readme_embedding_contract_test.go pins all four statements, in the spirit of #765 — the prose cannot drift from the code silently, and a failure is the signal to rewrite the bullet rather than the test.

--- PASS: TestREADMEExitIsReportedAsSuccess (0.02s)
    --- PASS: .../abort   --- PASS: .../exit   --- PASS: .../exit!
--- PASS: TestREADMERaiseBecomesAnError (0.01s)
--- PASS: TestREADMERubyHeapIsNotSharedBetweenCalls (0.01s)
--- PASS: TestREADMEProcessEnvIsSharedWithTheHost (0.01s)
ok  	github.com/go-embedded-ruby/ruby	1.108s

The raise-becomes-an-error test is there on purpose: without that twin, the exit-returns-nil test would also pass if Run swallowed every error. The cwd half of statement 1 is not tested — changing the test binary's working directory would disturb every other test in the package — and the test says so where it would be looked for. ENV is exercised through t.Setenv, so the framework restores it.

gofmt -l . is empty.

🤖 Generated with Claude Code