rubycc 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa70e92444211a2d9e68b297a9338d4d517f4c4ad746b95c3a3842e3347cb47f
+  data.tar.gz: f7139ecd66b6a7e3808da0f67f63edaaa8115620d92757bf6992656c1668bc49
+SHA512:
+  metadata.gz: a14a2b3a760995c8dbece07b44d6d5b6c779da09372c5a1a2aa7eb32e673a7bfa02f4c47559c66ee4485fc1a384c47179c307ed5df056b9479e87233d900a494
+  data.tar.gz: 5c5d8960ee72abf7cd8a64904b9063ae4a86d04d2a57a36b9a365ebf4078b0b53214818ab2b2826db8553aa7e7f4acc0d1a8ab7eaf9d7281a472f9ee0f6d2bff

data/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Notable changes per release. The per-step design record — why each decision was made,
+and what was measured to justify it — is in [docs/development/STEPS.md](docs/development/STEPS.md); this file is
+the summary a consumer of the gem needs.
+
+Versioning follows semver with one project-specific rule: **a regression in the corpus
+pass rate is a breaking change**, whatever the code change looked like. See the
+Versioning section of the README.
+
+## 1.0.0 (2026-08-12)
+
+First release. rubycc builds Ruby C extensions with no gcc, no binutils, no make and no
+shell — it is a C compiler, assembler-free ELF writer, linker, `ar`, `make`, `pkg-config`
+shim and preprocessor, written in Ruby.
+
+### What works
+
+- **31 gems verified**: bigdecimal, bootsnap, date, digest, erb, etc, fiddle,
+  google-protobuf, http_parser.rb, io-console, io-nonblock, io-wait, json, msgpack,
+  mysql2, nio4r, nkf, pg, prism, psych, puma, racc, redcarpet, sqlite3, stackprof,
+  stringio, strscan, syslog, websocket-driver, yajl-ruby, zlib. "Verified" means the
+  gem's own test suite passed against the `.so` that a `RUBYCC=1 gem install` produced
+  — the record is `data/verified_gems.json`, written only by
+  `tools/verify_gem_tests.rb`, never by hand. That is 31 of the 34 gems in the corpus
+  denominator (**91.2%**), meeting the 90% the design sets as its acceptance criterion.
+- **Two machines**: x86-64 and aarch64, each with its own backend and ABI.
+- **Two C libraries**: glibc and musl. The bundled headers carry both where they differ,
+  and every difference was measured against that environment's own gcc rather than
+  copied from a libc's sources.
+- **Bundled libc headers** so a distroless image with no libc development package still
+  compiles `ruby.h`.
+- `rubycc-doctor` reports whether a project's gems are known to build.
+
+### Known limitations
+
+Listed in full, with measurements, in the README. The ones most likely to matter:
+
+- Compile throughput is 69% of the 20,000 lines/sec target.
+- Generated code is unoptimized; up to 7.65x slower than `gcc -O2` on tight loops.
+- C11 atomics are partial: `_Atomic` compiles to the unqualified type's layout and ABI
+  for scalars of 1, 2, 4 and 8 bytes, and the bundled `<stdatomic.h>` carries the fences
+  and the generic macros; `atomic_fetch_or`/`_and`/`_xor`, `atomic_flag` and the implicit
+  sequential consistency of a plain access are missing.
+- `long double` is compiled as `double` (8 bytes, not the ABI's 80-bit x87 in 16), so it
+  loses precision and a value passed to `printf("%Lg", …)` reads back wrong.
+- Shared objects bind their own global symbols directly (`ld -Bsymbolic` semantics),
+  with no switch to turn it off.
+- 128-bit integers: passing, returning and shifting work; division, remainder, bitwise
+  operators and variadic passing do not.
+
+### Not in scope
+
+C++ (grpc), gems that run `configure` through mini_portile (nokogiri's vendored build —
+`--use-system-libraries` is fine), and gems that ship assembly (ffi). The full list with
+reasons is [docs/reference/OUT-OF-SCOPE-GEMS.md](docs/reference/OUT-OF-SCOPE-GEMS.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DATE Ken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/NOTICE

@@ -0,0 +1,52 @@
+rubycc
+======
+
+This product bundles a set of C library compatibility headers under
+`include/libc/` so that hosted translation units can be compiled without the
+target system's own libc development headers (the "distroless" use case).
+
+Portions of the bundled libc headers are derived from musl libc
+(https://musl.libc.org/), used as the starting point for the standard
+declarations, and then modified so their type widths, structure layouts and
+macro values match the glibc x86-64 ABI (measured from the reference platform,
+not copied from glibc). Each derived header carries a one-line provenance note
+in its opening comment; headers whose entire mechanism is glibc/arch specific
+(for example the <ctype.h> classification table accessors) or whose values come
+from the Linux kernel UAPI (<errno.h>, <sys/stat.h>) are written clean room
+against the published ABI rather than derived from musl.
+
+musl's COPYRIGHT grants permission for its public header files to omit the
+copyright and permission notices the MIT license would otherwise require, so
+retaining the musl notice below is not an obligation for the derived headers;
+rubycc keeps it as an acknowledgement of provenance. The full per-file
+provenance ledger and the licensing analysis are in docs/reference/HEADER-LICENSING.md.
+
+No source was copied from glibc (which is LGPL) or from the Linux kernel UAPI
+headers (which are GPL); only observable ABI facts (sizeof/_Alignof, offsetof,
+struct layouts, and macro values, printed by the reference compiler) were
+measured and reproduced. ABI facts are not copyrightable expression.
+
+musl libc
+---------
+
+Copyright (C) 2005-2020 Rich Felker, et al.
+
+musl is licensed under the MIT license:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# rubycc
+
+**Almost Pure Ruby C toolchain** — build Ruby native extensions without gcc, binutils, or a shell.
+
+rubycc is a C compiler, linker, archiver and `make` written entirely in Ruby. It compiles
+C to ELF64 machine code directly (no assembly text, no external assembler) and links
+shared objects itself, so a `gem install` that needs a C extension can run on a machine
+that has no toolchain installed.
+
+```
+$ RUBYCC=1 gem install msgpack
+Building native extensions. This could take a while...
+Successfully installed msgpack-1.8.3
+```
+
+## Status
+
+Working. The toolchain compiles and links real gems, and the gems' own test suites pass
+against the resulting binaries. **31 gems are verified this way**, each by running the
+gem's own suite against the `.so` a `RUBYCC=1 gem install` produced — never by inspection:
+
+    bigdecimal  bootsnap  date  digest  erb  etc  fiddle  google-protobuf  http_parser.rb
+    io-console  io-nonblock  io-wait  json  msgpack  mysql2  nio4r  nkf  pg  prism  psych
+    puma  racc  redcarpet  sqlite3  stackprof  strscan  stringio  syslog  websocket-driver
+    yajl-ruby  zlib
+
+The verified environments are:
+
+| environment | verified gems |
+|---|---|
+| glibc x86-64 | 31 |
+| musl x86-64 (Alpine) | 3 |
+| glibc aarch64 | 6 |
+
+The bundled headers match the ABI of the supported environments on both architectures
+and both C libraries.
+
+The current corpus census has 39 candidates, 34 gems in the R10 machine-gate denominator,
+and 31 verified gems: **91.2%**, which meets the 90% the design requires. `pg` and
+`sqlite3` are in that denominator through explicit DESIGN-compatible profiles (pg's
+native-source path, sqlite3 with `--enable-system-libraries`), so the rate is measured
+against a larger corpus than the 90.6% reported before those two were added. See
+[`test/corpus/include-census.md`](test/corpus/include-census.md) for the generated report.
+
+It also compiles the SQLite amalgamation — a single 261,463-line translation unit — in
+8.1 s using 467 MB of memory.
+
+## What's in the box
+
+| command | stands in for |
+|---|---|
+| `rubycc` | `cc` — preprocessor, compiler, linker driver (`-c`, `-o`, `-E`, `-shared`, `-fPIC`, `-I`, `-D`, `-L`, `-l`) |
+| `rmake` | `make` — parses Makefiles, runs recipes without a shell, parallel by default |
+| `rubycc-ar` | `ar` — deterministic archives |
+| `rubycc-pkgconf` | `pkg-config` |
+| `rubycc-doctor` | diagnostics: check an environment or a gem for compatibility |
+
+Targets **x86-64** and **aarch64** Linux (ELF64). The repository currently carries 81
+physical bundled header files, representing 64 normalized angle-bracket spellings in the
+census. They cover the C11 freestanding set plus the POSIX surface real gems use, so no
+libc development package is needed for the headers.
+
+## Requirements
+
+- **Ruby 3.3 or newer.** The suite is run on 3.3, 3.4 and 4.0; see *Known limitations*.
+- **Ruby's own headers** (`ruby.h` and friends) and `rbconfig`. Official ruby images have
+  them; on a distro Ruby you need the `-dev`/`-devel` package.
+- **Shared libraries you link against** must be present as binaries (`libc.so`, `libz.so`,
+  …). Their *headers* are not needed — the linker reads `.dynsym` and emits `DT_NEEDED`.
+- A Ruby built with `--enable-shared` is recommended, because mkmf's `try_link` conftests
+  link an executable.
+
+## Usage
+
+Set `RUBYCC=1` and install as usual:
+
+```sh
+RUBYCC=1 gem install <gem>
+```
+
+For a complete build-stage/runtime-stage example aimed at shell-less images,
+see [examples/distroless](examples/distroless/README.md).
+
+`RUBYCC=0` forces it off. With neither set, rubycc activates itself only when `cc` and
+`make` are absent from `PATH`, so it stays out of the way on a normal development machine.
+
+Direct use works too:
+
+```sh
+rubycc -c foo.c -o foo.o
+rubycc -shared -fPIC -o foo.so foo.o
+rubycc -E foo.c              # preprocess only
+rubycc --target=aarch64 -c foo.c -o foo.o
+```
+
+## Known limitations
+
+- **Compile speed is 69% of the target.** 13,854 preprocessed lines/sec (Ruby 4.0 + YJIT,
+  median over real gem sources) against a 20,000 goal. A typical gem still builds in
+  seconds.
+- **Generated code is unoptimized.** No register allocation: every value is spilled to the
+  stack. Against `gcc -O2` the slowdown reaches 7.65x on tight loops (1.2x–2.6x on
+  branch- and call-bound code); against `gcc -O0` it is 1.1x–2.9x.
+- **C11 atomics are partial.** `_Atomic` is accepted in both spellings (`_Atomic int`,
+  `_Atomic(int)`) and compiles to the unqualified type's layout and ABI — measured
+  against gcc — for integer, floating and pointer types of 1, 2, 4 or 8 bytes; an
+  aggregate, a 16-byte scalar, an array or a function under `_Atomic` is a compile
+  error rather than a silently non-atomic object. The bundled `<stdatomic.h>` provides
+  the memory-order constants, `atomic_thread_fence`/`atomic_signal_fence`,
+  `atomic_init`, and the load/store/exchange/compare-exchange/fetch-add/fetch-sub
+  generic macros, all lowered to locked machine sequences at 4 and 8 bytes.
+  What is missing: `atomic_fetch_or`/`_and`/`_xor`, `atomic_flag`,
+  `atomic_is_lock_free`, and the implicit sequential consistency C11 gives a plain
+  read or write of an `_Atomic` object (such an access compiles to an ordinary,
+  still-indivisible, instruction — use the macros where the ordering matters).
+  See `docs/reference/C11-COVERAGE.md`.
+- **C23 checked arithmetic is partial.** The bundled `<stdckdint.h>` maps `ckd_add`,
+  `ckd_sub`, and `ckd_mul` to rubycc's overflow builtins; the rest of C23 is not implemented.
+- **`<regex.h>` is a minimal ABI header.** It provides the glibc-compatible `regex_t`/
+  `regmatch_t` layout needed by C extensions, but the full POSIX regex implementation is
+  not part of rubycc.
+- **`__GNUC__` is deliberately not defined.** Headers take their non-GNU fallback path.
+- **128-bit integers**: passing, returning and shifting work; division, remainder, bitwise
+  `& | ^` and variadic passing do not.
+- **`long double` is 8 bytes** — it is compiled as `double`, where the x86-64 psABI gives
+  it 80-bit x87 extended precision in 16 bytes (and AArch64 gives it IEEE binary128).
+  Arithmetic therefore carries double's 53-bit significand, `sizeof(long double)` is 8,
+  and a `long double` handed to a variadic function does not match what the C library
+  reads back: `printf("%Lg", x)` prints a wrong number, because glibc's `printf` reads
+  16 bytes where rubycc pushed 8. This is measured, not theoretical — it is the one
+  difference between rubycc and the reference compiler in the `oj` gem's suite, whose
+  `usual.c` formats a `long double` that way. Code that only stores and computes with
+  `long double` gets double's range and precision; code that passes it across the libc
+  boundary gets wrong values. Full support needs x87 (and binary128) arithmetic and is
+  not in this release.
+- **Out of scope**: C++ input is rejected with a diagnostic (the compiler accepts C only),
+  so gems needing a C++ compiler (grpc) are out of scope. Gems that run `configure` through
+  mini_portile (nokogiri's vendored build; `--use-system-libraries` is fine), or that ship
+  assembly (ffi), are also out of scope.
+- **Shared objects bind their own global symbols directly.** A symbol a shared object
+  both defines and references resolves to that object's own definition, not to an
+  earlier one in the process — the behaviour `ld -Bsymbolic` gives, which many
+  distributions enable on purpose because it skips the PLT/GOT indirection. rubycc
+  always does it and offers no switch. Calls, struct passing, varargs and alignment
+  are unaffected; what changes is `LD_PRELOAD` interposition of such a symbol, and
+  the case where the same symbol is already defined elsewhere in the process (two
+  live copies instead of one).
+
+## No gem-side changes required
+
+Compatibility is rubycc's job, not the gem's. A gem must build **unmodified**: rubycc never
+asks for source changes, `extconf.rb` or gemspec edits, install-time patches, or
+rubycc-specific code such as `#ifdef __RUBYCC__`. If a gem does not build, that is a rubycc
+bug.
+
+Two things are *not* considered gem-side changes: turning rubycc on (`RUBYCC=1`), and
+choosing an install option the gem itself offers — for example
+`gem install nokogiri -- --use-system-libraries`, which is a supported flag of that gem,
+not a rubycc workaround.
+
+## Versioning
+
+Semantic versioning, with one project-specific rule:
+
+- **A regression in the corpus pass rate is a breaking change.** The corpus
+  (`test/corpus/gems.rb`, 39 candidates and currently 34 R10 machine-gate targets) is the
+  contract. The selected profile and exact extconf arguments are part of each target's
+  identity; they do not by themselves count as an upstream-suite verification.
+  If a release stops building a gem that the previous release built, that is major-version
+  territory, not a patch — regardless of how small the code change was.
+- **Minor** releases add language or header coverage, new targets, or new gems that build.
+- **Patch** releases fix bugs and improve performance without changing what builds.
+- The generated code's *speed* is not part of the compatibility contract, but throughput
+  and runtime performance are tracked (`rake bench:throughput`, `benchmark/run.rb`) and
+  regressions are treated as bugs.
+
+The full picture is in [docs/reference/C11-COVERAGE.md](docs/reference/C11-COVERAGE.md) (clause-by-clause C11
+conformance) and [docs/development/ROADMAP.md](docs/development/ROADMAP.md) §3 (known limitations).
+
+## How it works
+
+Source → preprocessor (translation phases 1–4) → parser → typed AST → IR → machine code →
+ELF writer. The linker resolves symbols, merges sections and emits `.so`/executables. No
+stage shells out; no stage writes assembly text.
+
+- [docs/development/DESIGN.md](docs/development/DESIGN.md) — requirements, architecture decisions, scope
+- [docs/internals/IR.md](docs/internals/IR.md) — the intermediate representation
+- [docs/development/RELEASE-CHECKLIST.md](docs/development/RELEASE-CHECKLIST.md) — non-functional requirement status
+- [docs/reference/HEADER-LICENSING.md](docs/reference/HEADER-LICENSING.md) — provenance of every bundled header
+
+## Development
+
+```sh
+rake test                  # full suite
+rake bench:throughput      # compile-speed benchmark (network: fetches gems)
+rake corpus:census         # which headers do real gems need? (network)
+R10_CORPUS_CACHE=... rake corpus:r10_scan # provenance + variadic candidates (no network)
+ruby benchmark/run.rb      # generated-code speed vs gcc
+```
+
+The suite compares rubycc against gcc on every layer it can: preprocessed token streams,
+exit codes and stdout of compiled programs, cross-architecture ABI probes, and the
+c-testsuite. gcc is a development-time dependency only — it is never required at runtime.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt) and [NOTICE](NOTICE) — the bundled headers' provenance
+is documented in [docs/reference/HEADER-LICENSING.md](docs/reference/HEADER-LICENSING.md).

data/data/README.md

@@ -0,0 +1,117 @@
+# data/ — repository-attached reference data
+
+## verified_gems.json
+
+The build-verified gem database `rubycc doctor` consults as its **primary
+reference** before attempting any on-the-fly build. JSON carries no comments, so
+the schema is documented here.
+
+Top level は **gem 名**をキーとするオブジェクト。1 gem = 1 エントリで、値は次のオブジェクト:
+
+| key             | type                       | meaning |
+|-----------------|----------------------------|---------|
+| `verifications` | array of verification 記録 | その gem を確認した**環境ごとの記録**。挿入順(古い順)。空にはしない |
+| `notes`         | string                     | 既知の但し書き(必要だったフラグ、手で補った手順など)。無ければ空文字 |
+
+`verifications` の各要素:
+
+| key           | type                | meaning |
+|---------------|---------------------|---------|
+| `versions`    | array of string     | この環境で検証したバージョン文字列(例 `"2.21.1"`)またはバージョン範囲(例 `">= 1.8, < 2"`)。ここに合致する gem は**ビルドせずに verified** と報告される |
+| `environment` | string              | その検証が成り立った環境。例 `"glibc x86_64 / ruby 3.4.5"` |
+| `verified_at` | string `YYYY-MM-DD` | その環境での検証を記録した日付 |
+| `evidence`    | string              | どう確認したか — どの rubycc ステップ/テストが証明したか(その gem 自身のテストスイートの合格など) |
+
+`versions` が**トップレベルではなく各記録の内側にある**のは、環境ごとに実際に検証した
+バージョンが違いうるからである。トップレベルに 1 本置くと、ある環境でしか測っていない
+バージョンまで全環境で検証済みだと主張することになる。
+
+同じ理由で、**ある環境で未検証であることは「その環境の記録が無いこと」で表す**。
+散文で書かない(下記「更新は…」節を参照)。
+
+### Version matching
+
+`versions` の各要素は、gem の解決済みバージョンに対して RubyGems の要求文法
+(`Gem::Requirement`)で照合される。`"2.21.1"` のような完全一致はそのバージョンだけに、
+`">= 1.8, < 2"` のような範囲はその内側の全バージョンに一致する。**どれか 1 つの記録の
+どれか 1 つの要素**を満たせばその gem は verified、つまり**どれか 1 つの環境で検証
+されていれば verified** である。`rubycc doctor` の note 欄には、実際に合致した記録の
+環境名が並ぶ。
+
+### What may be added here
+
+Only versions that were **actually built and exercised in this repository** — the
+initial data is `json 2.21.1` and `msgpack 1.8.3`, both of which built with
+rubycc and passed their own upstream test suites (Step 54, re-confirmed via the
+in-process rmake build in Step 61 and the hermetic gem install in Step 64). The
+intended long-term flow is to generate/extend this file from the corpus CI
+results (ROADMAP H3) rather than hand-editing it.
+
+### 更新は `tools/verify_gem_tests.rb` 経由で行う(手編集ではなく)
+
+上記の「手編集ではなくコーパス CI の結果から生成/拡張したい」という意図は
+**`tools/verify_gem_tests.rb` として実現済み**である。このツールは
+
+1. scratch GEM_HOME に本チェックアウトの rubycc を入れ、
+2. `RUBYCC=1 gem install <gem>` でその gem の C 拡張を rubycc でビルドし、
+3. 本当に rubycc が使われたことを RubyGems が残す痕跡
+   (`gem_make.out` の `$(MAKE)` = rubycc の `exe/rmake`、生成 Makefile の
+   `CC = <...>/exe/rubycc`)で確認し、
+4. 上流タグの tarball を取得して、そこへビルド済み `.so` を差し込み、
+5. **その gem 自身のテストスイート**を実走してサマリ行を実測パースする。
+
+**書き込み経路はこのツールの `--update --step N` だけ**である。PASS した gem
+だけが記録され、失敗した gem・サマリ行を読み取れなかった gem は決して書かれない。
+`evidence` / `environment` / `verified_at` はすべて**その実行の実測値**から生成
+される。書式(インデント 2、`versions` は 1 行のインライン配列)も既存に合わせて
+出力されるため、意図した行以外に差分は出ない。
+
+記録先の選び方は、その実行が**どの環境で走ったか**で決まる:
+
+- そのエントリに `environment` が一致する記録がある → **その記録だけ**を更新する
+  (`versions` は和集合、`verified_at` は当日、`evidence` は追記)。他の環境の記録は触らない
+- エントリはあるが、その環境の記録が無い → `verifications` の**末尾に新しい記録を足す**。
+  `evidence` はこのとき新規形から始める(他環境で測った証拠を引き継ぐと、
+  そこで測っていない事実をその環境で測ったことにしてしまう)
+- エントリ自体が無い → 記録 1 本と `notes` を持つ新エントリを作る
+
+```
+tools/verify_gem_tests.rb --all                          # 実走して報告するだけ
+tools/verify_gem_tests.rb --update --step 143 redcarpet  # 合格した gem を記録する
+```
+
+このツールを使ううえでの決まりごと:
+
+- **レシピには `sanity` 式が必須**。gem によっては C 拡張がロードされず純 Ruby の
+  フォールバック(racc)や処理系同梱の別コピー(date・bigdecimal・json)が使われても
+  テストスイートは合格しうる。実測例: racc の `cparse.so` を壊したままスイートを走らせると
+  **71 tests / 0 failures / 100% passed** になる(純 Ruby ランタイムに落ちている)。
+  sanity 式が無ければ、この状態が「rubycc で検証済み」として記録されてしまう。
+  そのためツールは `sanity` を持たないレシピの実行を拒否する。
+- **`notes` は人間の責務**であり、**このファイルで唯一、手で書き換えてよい欄**。
+  エントリ階層にあり、環境をまたいだ但し書きを書く。新規エントリで `--notes` を省略すると
+  空文字が入り、警告が出る。
+  「機械が観測できない但し書き」(racc の `lib/racc/parser-text.rb` を手で補った、など)は
+  必ず手で書き加えること。既存エントリを更新するとき、ツールは `notes` を**保持**する
+  (実測できる skip / pending / omission の件数だけは事実として追記する)。
+  ツールが上書きしないのは「機械が人間の但し書きを消さない」ためであって、
+  **人間が古くなった但し書きを直すのは正しい操作**である
+  (実例: stackprof の「`dlclose` 後始末は保証されない」は Step 156 で解消したので
+  手で書き換えた)。`versions` / `environment` / `verified_at` / `evidence` は
+  verification 記録の側にあり、実測から生成される欄なので、**手では触らない**こと。
+- **`notes` に「X ではまだ未検証」と書いてはならない**。ある環境で未検証であることは
+  **その環境の verification 記録が無いこと**で既に表現されている。散文にも書くと
+  同じ事実の管理箇所が 2 つになり、片方(必ず散文の側)が古くなる。実際、
+  全エントリが持っていた "musl and aarch64 not yet verified." がこれで、
+  スキーマを入れ子にしたときに削除した。
+- **既存の verification 記録の `evidence` は上書きではなく追記**される。`evidence` は
+  **その環境で**その gem を確認した全ステップの履歴を溜める欄で(json は Step 54・61・64、
+  msgpack は Step 138 で H4 の 1 文が足された)、今日の実走は「今日測った事実」を
+  足すだけであり、過去の確認が無かったことにはならない。上書きすると再実行では
+  復元できない部分が黙って消える。ただし**その環境の記録を新たに作るときは新規形から
+  始める**(他環境の履歴を引き継ぐと、そこで測っていない事実を主張することになる)。
+- **`test/test_doctor.rb` の許可リストは手で更新する**。
+  `test_verified_gems_json_holds_only_confirmed_gems` が持つ gem 名の許可リストと
+  DB のキー集合が食い違うと、ツールは貼り付け用の `assert_equal` 行を表示して警告する
+  だけで、テストファイルは決して自動編集しない(gem の追加を意識的な編集に留める
+  ための意図的なゲート)。