hegeltest 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecb67897e8ff8580eee45713f3ef1bf6f4f17878f5206830f40a47761ed1d193
-  data.tar.gz: 68143dade773e79ac88b16197a3213717808645b5e47f6799560867cac1c1009
+  metadata.gz: 19a8534cce74c0577ca61891ead16d02d336efd87f3178a8672d6482bed4c6bb
+  data.tar.gz: 65a01d9c2400e3890cab677cb3ada046341305caa514f9d18ddd069f8e537fb3
 SHA512:
-  metadata.gz: e91326c8d22876cddef53a04b3f62a6ff5b91929c70588e5117f1dbdb3089de014b4721c6058d0016a6b687585db6bfb72d90d6826aa04dc4e849c6a37090216
-  data.tar.gz: cd65227abec3bc433db3b1acc900050cfd403f8c76046309cff7c703c3025d99b665194b2c20b4b9627ca3b4d64ef5221e58779dfe373d1364f27b88dc579593
+  metadata.gz: 9a2c433f9d32ba001b0c7667ce248ffebf8dab48c48a0655050cf80e8c0113305a0c957436ad510dca730b5b9b583ed99f3388cd959831765a10327310a4d7fb
+  data.tar.gz: 715fc4b8c0a810e09382593cd2d0eba009da5b78bd6747bb23fdd599bd6d89c8262ce6ab0d7e70b24c0067b6387c1b57ce3420e4b2c1863ce9392eb463561110

data/CHANGELOG.md

@@ -2,6 +2,187 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-21
+
+### Engine: libhegel 0.48.0 (was 0.47.2)
+
+The [libhegel 0.48.0 release notes](https://github.com/hegeldev/hegel/releases/tag/libhegel/0.48.0)
+describe 0.48.0.
+
+Each platform gem carries `libhegel` 0.48.0. The engine adds one function to
+its C interface, `hegel_set_unicode_version`, and changes no other function.
+These bindings do not call it yet, so the string generators continue to use
+the newest Unicode tables of the engine, as before. A caller has nothing to
+change in code. The engine move changes these results for a caller:
+
+- With the default `report_multiple_failures: false`, a run can find a
+  different, smaller failure while it shrinks the first one. The run now
+  shrinks that failure too before it reports it. In 0.47.2, the run reported
+  that failure without shrinking it.
+- `from_regex` accepts the end-of-string anchor `\z`. In 0.47.2, a pattern
+  with `\z` raised `Hegel::Error` with `HEGEL_E_INVALID_ARG`.
+- `floats(min_value: Float::INFINITY, allow_infinity: false)` and
+  `floats(max_value: -Float::INFINITY, allow_infinity: false)` leave no value
+  to draw. The draw now raises `Hegel::Error` with `HEGEL_E_INVALID_ARG` and
+  a message that contains "leaves no value". In 0.47.2, the draw raised
+  `Hegel::Error` with `HEGEL_E_INTERNAL`.
+
+### Profiles
+
+`Hegel.test` takes `profile:`, the name of a settings profile to start the
+run from: a shipped one, one in `hegel.toml`, or one you register. Left
+`nil`, the run starts from the default profile as before, and a keyword
+passed alongside still beats the profile.
+
+`Hegel::Settings.register_profile(name, profile: nil, **keywords)`
+registers a profile for the whole process, and
+`Hegel::Settings.set_default_profile(name)` makes a profile the default
+for every run; `""` clears it. They follow hegel-rust's
+`Settings::register_profile` and `set_default_profile`. An unknown or
+reserved name raises `Hegel::Error` with the engine's message. See
+[ADR 0028](docs/adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md).
+
+### Settings
+
+`Hegel.test` takes five more keywords, with the names and meanings of
+hegel-rust's `Settings` methods. Each one left `nil` takes its value from
+the engine's settings profile, like `test_cases:` and `seed:`.
+
+- `stop_on_first_failure: false` keeps generating after a failure and
+  spends the whole `test_cases` budget before reporting.
+- `print_blob: false` leaves the `reproduce_failure:` line out of the
+  failure report. Left `nil`, a profile or `HEGEL_PRINT_BLOB` decides.
+- `show_statistics: true` makes the engine print, at the end of the run,
+  what `tc.event` and `tc.event_value` recorded.
+- `nondeterminism_strictness:` takes `:quiet`, `:warn`, or `:error`.
+  `:error` ends a run whose test behaves differently on a replay with
+  `Hegel::Error`.
+- `backend:` takes `:default` or `:urandom`.
+
+### Test location
+
+Every `Hegel.test` run now reports where its test lives to libhegel, with
+`hegel_settings_set_test_location`. Under Antithesis the engine writes one
+`always` assertion, "<class>::<function> passes properties", for each
+location; elsewhere it uses nothing, and no keyword changes. The file is
+relative to the working directory when it lies under it, and the class and
+function come from the frame that called `Hegel.test`. A call inside a
+block takes the name of the method holding the block, and a call outside
+any method, such as an RSpec example, takes the file without `.rb` as the
+class and `line <n>` as the function, so each example in a file has its
+own name.
+
+### Test cases
+
+`tc.event(label)` and `tc.event_value(label, value)` record what a test
+reached, for the statistics that `show_statistics: true` prints. They follow
+hegel-rust's `TestCase#event` and `TestCase#event_value`.
+
+### Generators
+
+- `date_strings`, `time_strings`, and `datetime_strings` generate ISO 8601
+  date, time, and datetime Strings, with no options, as hegel-rust does.
+  A time keeps nanoseconds: nine fractional digits appear when the
+  nanosecond is not zero.
+- `permutations`, `subsequences`, and `samples` draw reorderings, ordered
+  subsets, and samples of a given sequence, as hegel-rust does. Its
+  `with_replacement` and `without_replacement` setters are one keyword here,
+  `samples(replacement: true)`, which is the default.
+- `durations(min_value: 0, max_value: 2**64 - 1)` draws a duration as an
+  `Integer` count of nanoseconds, as hegel-rust's `durations` does for a
+  `Duration`. It follows [ADR 0030](docs/adr/0030-represent-a-duration-as-integer-nanoseconds.md).
+- `arrays(elements, unique: true)` draws an array with no two equal entries,
+  as hegel-rust's `vecs(...).unique(true)` does. An element equal to one
+  already drawn is rejected and drawn again, so `min_size` still counts
+  distinct entries.
+- `floats(allow_subnormal: nil)` allows or rules out subnormal values, as
+  hegel-rust's `allow_subnormal` does. Left `nil`, it allows them whenever
+  the bounds admit one. A `floats` call whose bounds admit none, such as
+  `floats(min_value: 1.0, max_value: 2.0)`, now tells the engine so.
+- `recursive(leaf, max_depth: 32, max_leaves: 100) { |subtrees| ... }`
+  draws a recursively defined value, such as a tree, through the engine's
+  recursion calls, as hegel-rust's `recursive` does. The engine decides each
+  leaf-or-branch choice and owns both budgets. An attempt that outgrows
+  `max_leaves` is drawn again from the root, and the spans it opened are
+  discarded, not kept. See
+  [ADR 0032](docs/adr/0032-suppress-span-closes-while-an-abandoned-recursion-attempt-unwinds.md).
+
+### Text generators
+
+`text` and `characters` take `categories:`, `exclude_categories:`,
+`include_characters:`, and `exclude_characters:`, with the names hegel-rust
+gives them. `text` also takes `alphabet:`, a `String` of the permitted
+characters, and raises `Hegel::Error` at draw
+time when it is combined with another character option. `from_regex` takes
+`alphabet:`, a `characters` generator that limits every character of the
+string, padding included. An unknown `codec:` now raises `"text: invalid
+codec: ..."` (or `characters:`) before the engine is called, and a
+surrogate category in `categories:` raises too.
+
+### Grammar strings
+
+`from_lark(grammar)` draws strings that a grammar written in the syntax of
+the [Lark](https://lark-parser.readthedocs.io/en/stable/grammar.html)
+parsing library accepts, as hegel-rust's `from_lark` does. It takes
+`start:`, `explicit:` (a `Hash` from terminal name to a generator of the
+values drawn for it), `alphabet:` (a `characters` generator),
+`max_size:`, `max_depth:`, and `import_path:`. An invalid option raises
+`Hegel::Error` at draw time, with hegel-rust's message where it has one.
+A grammar is compiled on its first draw in a run and freed when the run
+ends.
+
+### Added
+
+- `rule(name, weight: 1.0)` sets how often the engine picks a rule relative to
+  the machine's other rules, as `#[rule(weight = w)]` does in hegel-rust. A
+  weight that is not finite and positive raises `Hegel::Error` when the machine
+  runs. `Hegel::StateMachine.rule_definitions` now maps each name to a
+  `Hegel::StateMachine::Rule` with `block` and `weight`, where it mapped to the
+  block alone.
+
+### Fixed
+
+- A filter on `Pool#values_consumed` no longer loses the values it rejects. They
+  go back into the pool through `hegel_pool_restore` once the draw is over, and
+  only the accepted value is consumed, as in hegel-rust.
+
+### Changed
+
+Three defaults now match hegel-rust, which defines the interface. The results
+change for a caller who relied on the old default.
+
+- `from_regex` defaults to `fullmatch: true`, where it was `false`. The whole
+  drawn string matches the pattern, instead of merely containing a match. To
+  keep the old behaviour, pass `fullmatch: false`.
+- `text` defaults `max_size` to 100, where it was unbounded. When `min_size`
+  is above 100, the default is `min_size + 100`. Strings drawn without a
+  `max_size` are shorter than before. To draw longer strings, pass the
+  larger `max_size` you need.
+- `binary` defaults `max_size` the same way, to 100 or `min_size + 100`.
+
+- A filter over a filter now spends 3 attempts between the two predicates, as
+  hegel-rust does, where each level used to spend 3 of its own.
+- `Hegel::Generator#do_draw_filtered(tc, predicate)` is the draw behind
+  `#filter`. A generator whose draws have effects that a rejected value must
+  not keep overrides it.
+
+### Repeat a test body
+
+`tc.repeat { ... }` runs its block again and again, for as long as the
+engine keeps the loop going, the way hegel-rust's `TestCase::repeat` does.
+The engine chooses how many times it runs, and shrinks a failure toward
+fewer iterations. Each iteration shows in the failure report as a
+`// Repetition #N` line, with what the iteration recorded indented under
+it. A `tc.assume` or `tc.reject` inside the block skips that iteration
+instead of discarding the whole test case.
+
+The loop does not return when it ends. It raises `Hegel::LoopDone`, which
+`Hegel.test` counts as a passing test case. It descends from `Exception`,
+like the other control exceptions, so a `rescue => e` in the body does not
+catch it. A `break` in the block ends the loop and returns from
+`tc.repeat`. See
+[ADR 0034](docs/adr/0034-repeat-a-test-body-with-a-ruby-side-indent.md).
+
 ## [0.3.4] - 2026-10-20
 
 ### Engine: libhegel 0.47.2 (was 0.47.1)
@@ -273,6 +454,7 @@ The engine is called through the `ffi` gem. Each platform gem carries the
 matching `libhegel` 0.32.5 build. The platform-independent gem carries none,
 so a run on it needs `HEGEL_LIBHEGEL_PATH` pointing at a local build.
 
+[0.4.0]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.4.0
 [0.3.4]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.4
 [0.3.3]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.3
 [0.3.2]: https://github.com/meganemura/hegel-ruby/releases/tag/v0.3.2

data/README.ja.md

@@ -0,0 +1,408 @@
+# Hegel for Ruby
+
+[English README](README.md)
+
+> [!IMPORTANT]
+> **これは非公式のサードパーティ実装です。** Hegel プロジェクトと `libhegel`
+> エンジンは Antithesis, LLC のものです。このリポジトリは Antithesis とも
+> `hegeldev` organization とも関係がなく、先方のレビューや承認も受けていません。
+>
+> 公式実装は
+> [Rust](https://github.com/hegeldev/hegel/tree/main/frontends/rust)、
+> [Go](https://github.com/hegeldev/hegel-go)、
+> [C++](https://github.com/hegeldev/hegel-cpp)、
+> [TypeScript](https://github.com/hegeldev/hegel-typescript)、
+> [Java](https://github.com/hegeldev/hegel-java)、
+> [OCaml](https://github.com/hegeldev/hegel-ocaml) です。この gem の問題は
+> 公式実装ではなく、このリポジトリに報告してください。
+
+> [!NOTE]
+> Hegel 自体はベータ版で、今後も互換性のない変更が入る予定です。
+> <https://hegel.dev/compatibility> を参照してください。
+
+Hegel は [Hypothesis](https://github.com/hypothesisworks/hypothesis) を土台にした
+プロパティベーステストのフレームワークです。手で選んだ入力でテストを書く代わりに、
+どの入力でも成り立つべき性質を書きます。Hegel は入力を生成して性質を破ろうとし、
+失敗を見つけたら最小の反例まで縮めます。
+
+この gem は、公式実装も使っているネイティブエンジン
+[libhegel](https://hegel.dev/reference/libhegel) を
+[`ffi`](https://github.com/ffi/ffi) gem 経由で同じプロセス内で動かします。
+サーバーも Python も要りません。
+
+## インストール
+
+gem 名は [`hegeltest`](https://rubygems.org/gems/hegeltest) です。
+
+```ruby
+# Gemfile
+gem "hegeltest", group: :test
+```
+
+require パスは `hegel`、名前空間は `Hegel` です。Bundler の自動 require のために
+`require "hegeltest"` も使えます。
+
+Ruby 3.4 以上が必要です。各プラットフォーム向け gem には対応する `libhegel` の
+ビルドが同梱されているので、インストール時にコンパイルは不要で、エンジンを
+別に用意する必要もありません。
+
+| プラットフォーム | gem のプラットフォーム |
+| --- | --- |
+| Linux x64 | `x86_64-linux` |
+| Linux arm64 | `aarch64-linux` |
+| macOS arm64 | `arm64-darwin` |
+| Windows x64 | `x64-mingw-ucrt` |
+| Windows arm64 | `aarch64-mingw-ucrt` |
+
+Hegel のメンテナーは、サードパーティによるリリースバイナリの再配布を認めています
+([hegeldev/hegel-rust#411])。
+
+すでに `Gemfile.lock` があるプロジェクトでは、もう一手間要ります。Bundler は
+`bundle install` を実行したマシンのプラットフォームしか lock に足さないので、
+Mac で作った lock には Linux が載りません。そのままだと Linux の CI で gem が
+見つかりません。CI で使うプラットフォームを追加してください。
+
+```bash
+bundle lock --add-platform x86_64-linux
+```
+
+Intel Mac のように `libhegel` のビルドが公開されていないプラットフォームでは、
+エンジンを自分でビルドし、`HEGEL_LIBHEGEL_PATH` にそのライブラリファイルか、
+それを含むディレクトリを指定してください。同じ変数で、どのプラットフォームでも
+同梱のエンジンの代わりにローカルビルドを使えます。
+
+[hegeldev/hegel-rust#411]: https://github.com/hegeldev/hegel-rust/issues/411
+
+### どの libhegel が入っているか
+
+gem の各リリースは libhegel のリリースを 1 つ固定しています。インストール済みの
+gem が固定しているバージョンは次のコマンドで確認できます。
+
+```bash
+ruby -rhegel -e 'puts Hegel::LIBHEGEL_VERSION'
+```
+
+[CHANGELOG](CHANGELOG.md) の各リリースの節は、エンジンの更新があればその内容から
+始まり、そのエンジンのリリースノートにリンクしています。
+[GitHub Releases](https://github.com/meganemura/hegel-ruby/releases) にも
+同じ内容が載ります。
+
+libhegel の新しいリリースが出ると、それに追従する pull request が作られます。
+gem のバージョンとエンジンのバージョンは独立していて、gem のリリースには
+エンジンの更新、Ruby コードの変更、またはその両方が含まれます。
+
+## クイックスタート
+
+```ruby
+# spec/spec_helper.rb
+require "hegel"
+
+RSpec.configure do |config|
+  config.include Hegel::Syntax::Methods
+end
+```
+
+```ruby
+# spec/my_sort_spec.rb
+def my_sort(ls) = ls.sort.uniq # oops: uniq drops duplicates
+
+RSpec.describe "my_sort" do
+  it "matches the builtin sort" do
+    Hegel.test do |tc|
+      xs = tc.draw(arrays(integers))
+      expect(my_sort(xs)).to eq(xs.sort)
+    end
+  end
+end
+```
+
+このテストは失敗し、Hegel はバグを再現する最小の入力まで縮めます。
+レポートは次のようになります。
+
+```
+Falsified after 11 test cases (0 discarded):
+
+  xs = [0, 0]
+
+To reproduce this failure, pass the blob below to Hegel.test:
+    reproduce_failure: "AXicY2VgYGBkZOBiZEBhMAAAAd8AIQ=="
+```
+
+テストケースの数と blob は実行ごと、エンジンのリリースごとに変わります。
+見るべきなのは縮めた値で、重複が 2 つあれば十分だとわかります。Hegel は
+draw を書いた行を読んで値に `xs` という名前を付け、RSpec 自身の expectation
+失敗を投げ直すので、RSpec は普段どおりの失敗として報告します。
+
+`Hegel::Syntax::Methods` を include すると、FactoryBot の `create` のように
+ジェネレーターを接頭辞なしで使えます。include しなくても
+`Hegel::Generators.arrays(...)` として使えます。
+
+独自のヘルパーを持つ example group にジェネレーター名を持ち込みたくない場合は、
+タグを付けた group だけに include します。
+
+```ruby
+config.include Hegel::Syntax::Methods, :hegel
+```
+
+Hegel は値を命令的に draw するので、普通の Ruby メソッドで複数の draw を
+プロパティ間で共有できます。メソッドの引数には、RuboCop の既定の命名規則に
+合う説明的な名前を付けてください。
+
+```ruby
+def draw_sorted_pair(test_case)
+  low = test_case.draw(integers(min_value: 0, max_value: 100))
+  high = test_case.draw(integers(min_value: low, max_value: 200))
+  [low, high]
+end
+
+Hegel.test do |tc|
+  low, high = draw_sorted_pair(tc)
+  expect(low).to be <= high
+end
+```
+
+### Minitest
+
+Hegel はテストフレームワークに何も要求しません。ジェネレーターのメソッドを
+一度 include し、普通のテストの中にプロパティを書きます。
+
+```ruby
+# test/test_helper.rb
+require "hegel"
+
+class Minitest::Test
+  include Hegel::Syntax::Methods
+end
+```
+
+```ruby
+# test/my_sort_test.rb
+class MySortTest < Minitest::Test
+  def test_matches_the_builtin_sort
+    Hegel.test do |tc|
+      xs = tc.draw(arrays(integers))
+      assert_equal xs.sort, my_sort(xs)
+    end
+  end
+end
+```
+
+Minitest は縮めたケースを、テストを書いた行での通常の assertion 失敗として
+報告します。
+
+```
+1) Failure:
+MySortTest#test_matches_the_builtin_sort [test/my_sort_test.rb:5]:
+Expected: [0, 0]
+  Actual: [0]
+```
+
+## ジェネレーター
+
+| 種類 | ジェネレーター |
+| --- | --- |
+| 数値と真偽値 | `integers`, `floats`, `booleans` |
+| 文字列とバイト列 | `text`, `characters`, `binary`, `from_regex`, `from_lark` |
+| コレクション | `arrays`, `sets`, `hashes`, `tuples` |
+| 選択 | `just`, `sampled_from`, `permutations`, `subsequences`, `samples`, `one_of`, `optional` |
+| 書式 | `emails`, `urls`, `domains`, `ip_addresses`, `uuids` |
+| 日時 | `dates`, `times`, `datetimes`, `date_strings`, `time_strings`, `datetime_strings`, `durations` |
+| 自作 | `composite`, `deferred`, `recursive` |
+
+どれも `map` と `filter` で組み合わせられます。オプションはキーワード引数で、
+`integers(min_value: 0, max_value: 9)`、`arrays(text, max_size: 5)`、`arrays(integers, unique: true)` のように、
+他の Hegel 実装と同じ名前を使います。オプションの組み合わせが不正な場合は、
+ジェネレーターを作ったときではなく draw したときに例外になります。
+
+## ステートフルテスト
+
+入力 1 つではなく、操作の列で初めて出るバグもあります。操作を
+`Hegel::StateMachine` のルールとして宣言すると、Hegel が次に実行するルールを選び、
+途中で不変条件を確かめ、失敗をそれが再現する最短の操作列まで縮めます。
+
+```ruby
+class StackMachine < Hegel::StateMachine
+  def initialize
+    @stack = BoundedStack.new(3)
+    @model = []
+  end
+
+  rule :push do |tc|
+    x = tc.draw(integers(min_value: 0, max_value: 9))
+    @stack.push(x)
+    @model.push(x) if @model.size < 3
+  end
+
+  rule :pop do |tc|
+    tc.assume(!@model.empty?)
+    raise "pop disagreed" unless @stack.pop == @model.pop
+  end
+
+  invariant :size_agrees do
+    raise "size disagreed" unless @stack.size == @model.size
+  end
+end
+
+Hegel.test { |tc| Hegel::Stateful.run(StackMachine.new, tc) }
+```
+
+ルールの中の `tc.assume` は、テストケース全体を捨てるのではなく、そのルールだけを
+却下して別のルールを選ばせます。`alloc` が返したハンドルを解放するなど、前のルールが
+作った値を使うルールでは、値を `Hegel::Stateful::Pool` に入れて、そこから draw します。
+
+すべての不変条件は最初のルールの前と最後のルールの後に実行されます。ルールの間では
+エンジンが各不変条件をサンプリングします。毎回のルールの後に確かめたい不変条件は
+`always_run: true` 付きで宣言してください。
+`Hegel::Stateful.run(machine, tc, step_count: 50)` で 1 テストケースあたりの最大
+ルール数を指定できます。既定は 50 です。`rule :name, weight: 2.5` と書くと、そのルールが
+他より選ばれやすくなります。既定の重みは 1.0 です。
+
+## 実行の設定
+
+`Hegel.test` は次のキーワードを受け取ります。
+
+| キーワード | 効果 |
+| --- | --- |
+| `profile` | 実行の出発点にする設定プロファイル。[プロファイル](#プロファイル)を参照 |
+| `test_cases` | 生成するテストケースの数 |
+| `seed` | ランダム生成のシード |
+| `derandomize` | 生成を決定的にする |
+| `verbosity` | エンジンの出力量。`:quiet` は失敗レポートも隠す |
+| `phases` | 生成や縮小など、実行するエンジンのフェーズ |
+| `suppress_health_check` | 無効にするヘルスチェック |
+| `report_multiple_failures` | 異なる失敗をそれぞれ報告する。既定は `false` |
+| `stop_on_first_failure` | `false` にすると `test_cases` を使い切ってから報告する |
+| `print_blob` | `false` にすると失敗レポートから再現用の行を外す |
+| `show_statistics` | `tc.event` と `tc.event_value` で記録した内容を実行の最後に表示する |
+| `nondeterminism_strictness` | 再実行で振る舞いが変わるテストへの反応。`:quiet`、`:warn`、`:error` |
+| `backend` | `:default`、または値を引くたびに外部のエントロピーを使う `:urandom`(Antithesis 向け) |
+| `database_key` | このプロパティで example database を有効にする |
+| `database` | example database のディレクトリ |
+| `reproduce_failure` | レポートの blob から 1 つの失敗を再生する |
+
+指定しなかったキーワードは、エンジンの設定プロファイルの値になります。これは
+`hegel.toml` や `HEGEL_*` 環境変数で変えない限り libhegel 自身の既定値です。
+CI サーバー上ではエンジンが `ci` プロファイルを使い、実行を決定的にして
+example database を無効にします。
+
+example database は失敗したケースを保存し、次回最初に再生します。
+`database_key` で有効になり、`database` でディレクトリを選びます。
+
+```ruby
+Hegel.test(database_key: "my_sort matches the builtin sort") { |tc| ... }
+```
+
+プロパティごとに別のキーを付けてください。ディレクトリではなくキーで有効になる
+理由は [ADR 0009](docs/adr/0009-turn-the-example-database-on-with-a-key.md) に
+あります。
+
+テストの中では、`tc.note` で失敗レポートに出すメッセージを記録でき、
+`tc.target` で Hegel が探索を寄せる方向を指定でき、`tc.repeat` で
+Hegel が選んだ回数だけブロックを繰り返し実行できます。
+
+`tc.event` と `tc.event_value` は、テストが狙ったケースに届いているかを確かめる
+ためのものです。`show_statistics: true` にすると、各イベントが起きた割合と、
+各値の分布の要約をエンジンが表示します。数値は実行ごとに変わります。
+
+```ruby
+Hegel.test(show_statistics: true) do |tc|
+  xs = tc.draw(arrays(integers))
+  tc.event("empty") if xs.empty?
+  tc.event_value("size", xs.size)
+end
+```
+
+```
+Statistics (over 100 test cases):
+  * empty: 6.0% of test cases
+  * size: count 100, min 0, median 6, mean 7.99, p90 19, max 20
+```
+
+## プロファイル
+
+プロファイルは名前の付いた設定の組です。エンジンは `development`、`ci`、
+`workload` を同梱しており、`hegel.toml` でさらに定義できます。`profile:` を
+渡すと 1 回の実行をそのプロファイルから始められ、独自のプロファイルは
+`Hegel::Settings.register_profile` で登録できます。
+
+```ruby
+Hegel::Settings.register_profile("nightly", profile: "ci", test_cases: 10_000)
+
+Hegel.test(profile: "nightly") { |tc| ... }
+```
+
+`Hegel.test` に渡したキーワードはプロファイルより優先されます。名前を指定した
+プロファイルは既定のプロファイルを継承するので、設定していない項目は既定の
+プロファイルから来ます。`Hegel::Settings.set_default_profile("nightly")` は
+そのプロセスのすべての実行の既定にし、`set_default_profile("")` で解除します。
+登録と既定はプロセス全体に効き、すでに始まった実行は変わりません。
+`register_profile` は `database_key` を除く `Hegel.test` のキーワードを受け取ります。
+プロファイルは `database_key` を持たないためです。また `Hegel.test` は常に
+`report_multiple_failures` を渡すので、プロファイル側の値は使われません。
+未知の名前は `Hegel::Error` になります。
+[ADR 0028](docs/adr/0028-expose-settings-profiles-as-a-keyword-and-module-functions.md)
+を参照してください。
+
+## エージェント向けスキル
+
+2 つのスキルを組み合わせて使います。Hegel のメンテナーによる公式の
+[hegel-skill](https://github.com/hegeldev/hegel-skill) は、どの性質を探すか、
+エージェントが書いたテストをどう確かめるかといった手法を教えるもので、
+どの Hegel 実装でも使えます。[`skills/hegel-ruby`](skills/hegel-ruby/SKILL.md) は
+Ruby の部分、つまりこの gem の API と RSpec・Minitest での使い方を足します。
+両方をインストールしてください。
+
+Claude Code では、それぞれのリポジトリをマーケットプレイスとして追加し、
+プラグインをインストールします。
+
+```
+/plugin marketplace add hegeldev/hegel-skill
+/plugin install hegel-skill@hegeldev
+/plugin marketplace add meganemura/hegel-ruby
+/plugin install hegel-ruby@meganemura
+```
+
+Codex などほかのエージェントでのインストール方法は、
+[hegel-skill の README](https://github.com/hegeldev/hegel-skill#installation) を
+参照してください。この gem のスキルは、同じ手順で
+<https://github.com/meganemura/hegel-ruby/tree/main/skills/hegel-ruby> を指定すればインストールできます。
+
+## 開発
+
+```bash
+bin/setup                        # 依存関係をインストール
+bundle exec rake libhegel:fetch  # 固定したエンジンを SHA-256 で検証してダウンロード
+bundle exec rake                 # カバレッジ付きのテストとリンター
+bundle exec rake mutation        # ミューテーションテスト
+bin/console                      # 対話プロンプト
+```
+
+`just` のレシピは同じ Rake タスクを呼ぶので、他の Hegel 実装で `just` を使っている
+人は `just check`、`just test`、`just lint` をそのまま使えます。
+
+CI は pull request と main への push ごとに、上の表のすべてのプラットフォームで
+Ruby 3.4 と 4.0 のテストを実行します。
+
+設計の記録は [docs/](docs/README.md) にあります。
+
+### リリース
+
+main へのマージで `lib/hegel/version.rb` が変わると、リリースが始まります。
+Release ワークフローは `release` 環境の承認を待ち、承認されるとテストを実行し、
+gem を RubyGems に公開し、タグ `v<version>` と GitHub Release を作ります。
+リリースノートは [CHANGELOG.md](CHANGELOG.md) のそのバージョンの節から作られます。
+[ADR 0024](docs/adr/0024-release-when-a-merge-changes-the-gem-version.md) を
+参照してください。
+
+## コントリビュート
+
+バグ報告と pull request は <https://github.com/meganemura/hegel-ruby> へ。
+コントリビューターは[行動規範](CODE_OF_CONDUCT.md)に従ってください。
+
+## ライセンス
+
+この gem は [MIT License](LICENSE.txt) で利用できます。
+
+リリースされた gem には `libhegel` 自身のライセンス(MIT、copyright Antithesis, LLC)
+も含まれます。各プラットフォーム向け gem はエンジンの隣に `NOTICE-libhegel.txt` を
+同梱しており、その全文が入っています。