zizek 0.1.0

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,201 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/zizek-rb-logo-dark.svg">
+    <img src="docs/assets/zizek-rb-logo.svg" alt="Zizek.rb" width="320">
+  </picture>
+</p>
+
+# Zizek for Ruby
+
+This gem is the native Ruby runtime for Zizek property testing, based on
+[Hegel](https://hegel.dev) and
+[Hypothesis](https://hypothesis.readthedocs.io/en/latest/) and keeping them
+as oracle implementations. It explores generated examples, records every
+choice, shrinks the first failure, and raises a failure containing a portable
+reproduce blob.
+
+Roughly two thirds of the core behavior is compiled from the Hegel engine into
+`lib/zizek/gen.rb`; the rest is a curated shell that aims to be idiomatic Ruby.
+[dev.md](dev.md) describes the split.
+
+> ⚠️ **Status: experimental.** Behavior and the public API can still change and
+> be tweaked between releases.
+
+## Install
+
+```bash
+gem install zizek
+```
+
+Or, in a `Gemfile`:
+
+```ruby
+gem "zizek", "~> 0.1"
+```
+
+## Quick start
+
+```ruby
+require "zizek"
+
+property = lambda do |test_case|
+  value = test_case.draw(Zizek::Generators.integers(-100..100), name: :value)
+  raise "too large" unless value < 5
+end
+
+begin
+  Zizek.check(property, examples: 200, seed: 1)
+rescue Zizek::Failure => failure
+  puts failure.message
+
+  # Runs exactly the recorded, shrunk example and raises Failure again.
+  begin
+    Zizek.check(property, reproduce: failure.blob)
+  rescue Zizek::Failure
+  end
+end
+```
+
+The failure says which values failed, not just that something did:
+
+```
+Falsifying example: (value=5)
+RuntimeError: too large
+reproduce with: Zizek.check(property, reproduce: "AAEAAAAACgEAAAAF")
+seed: 1
+```
+
+`Zizek.check` also accepts a block, and `Zizek.run` returns the verdict as a
+value instead of raising:
+
+```ruby
+Zizek.check(examples: 200) do |test_case|
+  raise "too large" unless test_case.draw(Zizek::Generators.integers(-100..100)) < 5
+end
+
+Zizek.run(property, examples: 200, seed: 1).blob   # => "AAEAAAAACgEAAAAF"
+```
+
+## Generators
+
+Generators compose with `map`, `filter`, `|`, and `tuples`, and add no hidden
+choices, so a composed value shrinks and replays like a plain one:
+
+```ruby
+g = Zizek::Generators
+
+request = g.tuples(
+  g.sampled_from(%i[get post delete]),
+  g.none | g.text(min: 1, max: 8),
+  g.integers(0..10).filter(&:even?)
+)
+
+Zizek.check(examples: 200, seed: 7) do |test_case|
+  method, resource, _retries = test_case.draw(request)
+  raise "DELETE must name a resource" if method == :delete && resource.nil?
+end
+```
+
+## Test frameworks
+
+With Minitest, `property` defines a real test method:
+
+```ruby
+require "zizek/minitest"
+
+class SplitBillTest < Minitest::Test
+  include Zizek::Minitest
+
+  property "the split is exact",
+           total:  Zizek::Generators.integers(0..10_000),
+           people: Zizek::Generators.integers(1..50) do |total, people|
+    assert_equal total, Bill.split(total, people).sum
+  end
+end
+```
+
+With RSpec, it defines a real example:
+
+```ruby
+require "zizek/rspec"
+
+RSpec.describe Bill do
+  property "the split is exact",
+           total:  Zizek::Generators.integers(0..10_000),
+           people: Zizek::Generators.integers(1..50) do |total, people|
+    expect(described_class.split(total, people).sum).to eq(total)
+  end
+end
+```
+
+## Stateful testing
+
+Subclass `Zizek::Stateful::Machine` and declare rules and invariants; a
+failure shrinks to the shortest sequence of steps that still fails:
+
+```ruby
+class Counter < Zizek::Stateful::Machine
+  def initialize
+    @value = 0
+  end
+
+  rule(:increment) do |test_case|
+    @value += test_case.draw(Zizek::Generators.integers(0..10), name: :amount)
+  end
+
+  rule(:decrement) do |test_case|
+    test_case.assume(@value.positive?)
+    @value -= 1
+  end
+
+  invariant(:nonnegative) do
+    raise "negative" if @value.negative?
+  end
+end
+
+Zizek.check(Counter.property, examples: 500)
+```
+
+## Learn more
+
+- [GUIDE.md](GUIDE.md) walks through every feature with runnable examples:
+  settings and profiles, the example database, keyed draws, coverage
+  assertions, pools, and more.
+- [`examples/`](examples) holds runnable examples; each is listed in the
+  guide.
+- [dev.md](dev.md) covers the package layout, verification, and the upstream
+  example ports.
+- [CHANGELOG.md](CHANGELOG.md) records each release.
+
+## Functionality available now
+
+- Sequential property exploration with deterministic seeds.
+- Generation-phase mutation that duplicates same-label spans to discover
+  repeated values and repeated state-machine operations.
+- Recorded integer, boolean, byte-string, IEEE-754 float, and Unicode text choices.
+- Uniform narrow integer draws and swarm-biased wide ones.
+- Composable generators accepted by `test_case.draw`.
+- Assumption-based rejection with configurable limits.
+- Exception and returned-`false` failure capture.
+- Variable-length `Generators.lists` whose elements shrink by deletion, plus
+  `Generators.sets`, `Generators.hashes`, and `lists(unique_by:)` for distinct
+  elements.
+- Per-choice shrinking plus element-span and rule-span deletion.
+- Cloned streams: `test_case.clone_stream` returns a child test case drawing from
+  a stream of its own, framed in the parent's blob and shrunk by the same
+  schedule.
+- Portable replay with choice punning and overrun detection, with punned
+  draws counted and reported on the failure.
+- An example database that stores counterexamples between runs and replays them
+  before generating — in a layout the Python and Go packages share.
+- State machines as classes (`Zizek::Stateful::Machine` with `rule` and
+  `invariant`) or as hand-built rule arrays, with a default budget of 50
+  successful steps (rejected rules spend an attempt, not a step).
+- Reusable and consumed arbitrary Ruby-object pools.
+- Named draws, reported as a falsifying example on the failure.
+- Frozen `Settings` objects and named profiles, so a suite configures itself
+  once instead of at every call site.
+- `Zizek.run` for the verdict as a value, alongside `Zizek.check`.
+- Minitest and RSpec integrations that define real tests in each framework.
+- Runnable ports of Hypothesis's introductory example and all five top-level
+  Hegel examples, including the ledger acceptance case.

data/docs/assets/zizek-rb-logo-dark.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-70 -20 1040 970" width="1040" height="970" role="img" aria-label="Zizek.rb">
+  <title>Zizek.rb</title>
+  <!-- shrinking counterexample: each pass narrows the failing input until only
+       the minimal reproducer (the accent square) is left -->
+  <g>
+    <rect x="125" y="40"  width="475" height="110" fill="#eef1fa"/>
+    <rect x="243" y="160" width="357" height="105" fill="#a9c4f7"/>
+    <rect x="363" y="273" width="230" height="94"  fill="#5b9cf0"/>
+    <rect x="460" y="375" width="173" height="73"  fill="#2f7ce6"/>
+    <rect x="545" y="455" width="130" height="65"  fill="#1a5fd0"/>
+    <rect x="670" y="525" width="45"  height="43"  fill="#ff5f70"/>
+  </g>
+  <text x="450" y="880" fill="#eef1fa" text-anchor="middle"
+        font-family="'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif"
+        font-size="265" font-weight="600" letter-spacing="-5">&#381;i&#382;ek<tspan fill="#ff5f70">.rb</tspan></text>
+</svg>

data/docs/assets/zizek-rb-logo.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-70 -20 1040 970" width="1040" height="970" role="img" aria-label="Zizek.rb">
+  <title>Zizek.rb</title>
+  <!-- shrinking counterexample: each pass narrows the failing input until only
+       the minimal reproducer (the accent square) is left -->
+  <g>
+    <rect x="125" y="40"  width="475" height="110" fill="#17224e"/>
+    <rect x="243" y="160" width="357" height="105" fill="#0f47b4"/>
+    <rect x="363" y="273" width="230" height="94"  fill="#2277e0"/>
+    <rect x="460" y="375" width="173" height="73"  fill="#5b9cf0"/>
+    <rect x="545" y="455" width="130" height="65"  fill="#7fb2f5"/>
+    <rect x="670" y="525" width="45"  height="43"  fill="#cc0f2b"/>
+  </g>
+  <text x="450" y="880" fill="#17224e" text-anchor="middle"
+        font-family="'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif"
+        font-size="265" font-weight="600" letter-spacing="-5">&#381;i&#382;ek<tspan fill="#cc0f2b">.rb</tspan></text>
+</svg>

data/examples/combinators.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Composing generators: the blob stays portable, the shrinker stays sharp.
+#
+# Demonstrates:
+#   - `builds` assembling a struct from drawn parts;
+#   - `sampled_from`, `map`, `filter`, and `|` (one_of) layered on top;
+#   - `composite` for a draw that depends on an earlier draw; and
+#   - shrinking straight through the composition: combinators add no hidden
+#     choices, so the minimal counterexample is minimal in every field at
+#     once.
+#
+# Both scenarios are deterministic: fixed seeds, printed shrunk failures.
+
+require "zizek"
+
+module CombinatorsExample
+  G = Zizek::Generators
+
+  Request = Struct.new(:verb, :path, :body, :retries)
+
+  module_function
+
+  # A generator per field, assembled with `builds`:
+  #   - `sampled_from` picks a verb, shrinking towards the first;
+  #   - `map` turns drawn text into a path without recording extra choices;
+  #   - `|` makes the body optional, shrinking towards the left (nil) side;
+  #   - `filter` keeps only even retry counts, rejecting rather than failing.
+  def requests
+    G.builds(
+      Request,
+      verb: G.sampled_from(%i[get put delete]),
+      path: G.text(min: 1, max: 8, alphabet: "abc").map { |name| "/#{name}" },
+      body: G.none | G.text(min: 1, max: 6, alphabet: "xyz"),
+      retries: G.integers(0..9).filter(&:even?)
+    )
+  end
+
+  # The bug: the router forwards a DELETE body instead of rejecting it. The
+  # shrunk request is minimal in every field the failure does not need —
+  # shortest path, smallest retries — while `verb` stays `:delete` and `body`
+  # stays present, because the failure needs them.
+  def delete_with_a_body
+    property = lambda do |test_case|
+      request = test_case.draw(requests, name: :request)
+      raise "refusing to forward a DELETE with a body" if
+        request.verb == :delete && !request.body.nil?
+    end
+
+    begin
+      Zizek.check(property, examples: 500, seed: 2)
+      raise "the DELETE-with-body bug should be discovered"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # `composite` is for a generator whose later draws depend on earlier ones:
+  # here a meeting that must end no earlier than it starts. The block gets
+  # the test case itself, so it can draw, assume, and note like a property.
+  def meetings
+    G.composite do |t|
+      starts = t.draw(G.integers(0..23))
+      ends = t.draw(G.integers(starts..23))
+      [starts, ends]
+    end
+  end
+
+  # The bug: the scheduler double-books the noon slot. The failure needs a
+  # meeting spanning hour 12, so the shrunk example is the earliest start
+  # with the earliest end that still covers it.
+  def meeting_across_noon
+    property = lambda do |test_case|
+      starts, ends = test_case.draw(meetings, name: :meeting)
+      test_case.note("meeting #{starts}:00-#{ends}:59")
+      raise "the noon slot was double-booked" if starts <= 12 && ends >= 12
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "the noon double-booking should be discovered"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts "== 1. builds + sampled_from + map + filter + | =="
+  puts CombinatorsExample.delete_with_a_body.message
+  puts "\n== 2. composite: dependent draws =="
+  puts CombinatorsExample.meeting_across_noon.message
+end

data/examples/coverage_assertions.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Coverage assertions: catching the test that passes for the wrong reason.
+#
+# Demonstrates:
+#   - `always`, an ordinary failure that shrinks to the boundary it crossed;
+#   - `unreachable`, shrinking to the simplest input reaching a branch;
+#   - `sometimes`, failing a run whose interesting branch never executed;
+#   - `cover(percent:)`, requiring a rate rather than a single sighting; and
+#   - `must_cover:`, declaring a label whose call site itself may never run.
+#
+# The code under test is a clamp that forgot its ceiling. Every scenario is
+# deterministic: it uses a fixed seed and prints the verdict it expects.
+
+require "zizek"
+
+module CoverageAssertionsExample
+  module_function
+
+  # Clamp `value` into [floor, ceiling]. Deliberate bug: the ceiling check
+  # compares against the floor, so values above the ceiling pass through.
+  def clamp(value, floor, ceiling)
+    return floor if value < floor
+    return ceiling if value < floor # BUG: should be `if value > ceiling`
+
+    value
+  end
+
+  # `always` is a per-example assertion. It fails like any other failure, so
+  # it shrinks: the reported example is the *smallest* value that escapes the
+  # ceiling, 101, not whatever large value was found first.
+  def always_shrinks_to_the_boundary
+    property = lambda do |test_case|
+      value = test_case.integer(0, 1000)
+      clamped = clamp(value, 0, 100)
+      test_case.always("clamped into range", clamped.between?(0, 100))
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "the broken ceiling should be discovered"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # `unreachable` asserts a branch is dead. When it is not, the failure
+  # shrinks to the simplest input that reaches it.
+  def unreachable_finds_the_simplest_path
+    property = lambda do |test_case|
+      value = test_case.integer(0, 1000)
+      test_case.unreachable("value escaped the clamp") if clamp(value, 0, 100) > 100
+    end
+
+    begin
+      Zizek.check(property, examples: 300, seed: 1)
+      raise "the escape branch should be reached"
+    rescue Zizek::Failure => failure
+      failure
+    end
+  end
+
+  # `sometimes` judges the completed run, not the current example. Here the
+  # property itself holds on every draw — the generator never exceeds the
+  # ceiling, so the clamp is never exercised where it is broken. Without the
+  # coverage assertion this run would go green and prove nothing.
+  def sometimes_fails_the_vacuous_pass
+    property = lambda do |test_case|
+      value = test_case.integer(0, 100) # never above the ceiling: too narrow
+      clamped = clamp(value, 0, 100)
+      test_case.sometimes("saturated at the ceiling", clamped == 100 && value > 100)
+      raise "clamp raised the value" if clamped > value
+    end
+
+    begin
+      Zizek.check(property, examples: 200, seed: 1)
+      raise "the run should fail its coverage requirement"
+    rescue Zizek::FailedCoverage => missed
+      missed
+    end
+  end
+
+  # `cover` is `sometimes` with a required rate over the run's valid examples.
+  # Values 0..1000 clamped into [0, 100] leave ~90% of draws above the
+  # ceiling, so demanding that 60% of examples stay *below* it must fail —
+  # and the verdict reports the observed counters.
+  def cover_reports_the_observed_rate
+    property = lambda do |test_case|
+      value = test_case.integer(0, 1000)
+      test_case.cover("left below the ceiling", value <= 100, percent: 60)
+    end
+
+    begin
+      Zizek.check(property, examples: 200, seed: 1)
+      raise "the run should miss the 60% requirement"
+    rescue Zizek::FailedCoverage => missed
+      missed
+    end
+  end
+
+  # A call site registers its label the first time it *runs*. This
+  # `sometimes` sits inside a branch the generator can never enter, so the
+  # run never even learns the label exists — declaring it in `must_cover:`
+  # is what turns that silence into a verdict.
+  def must_cover_catches_the_unregistered_label
+    property = lambda do |test_case|
+      value = test_case.integer(0, 50)
+      if value > 100 # unreachable with these bounds
+        test_case.sometimes("overflow path", true)
+      end
+    end
+
+    begin
+      Zizek.check(
+        property,
+        examples: 100,
+        seed: 1,
+        must_cover: [Zizek::Coverage.new("overflow path")]
+      )
+      raise "the run should fail the declared requirement"
+    rescue Zizek::FailedCoverage => missed
+      missed
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  puts "== 1. always: fails and shrinks to the boundary =="
+  puts CoverageAssertionsExample.always_shrinks_to_the_boundary.message
+  puts "\n== 2. unreachable: shrinks to the simplest reaching input =="
+  puts CoverageAssertionsExample.unreachable_finds_the_simplest_path.message
+  puts "\n== 3. sometimes: the vacuous pass becomes a failure =="
+  puts CoverageAssertionsExample.sometimes_fails_the_vacuous_pass.message
+  puts "\n== 4. cover: a required rate, with observed counters =="
+  puts CoverageAssertionsExample.cover_reports_the_observed_rate.message
+  puts "\n== 5. must_cover: a label whose call site never ran =="
+  puts CoverageAssertionsExample.must_cover_catches_the_unregistered_label.message
+end