predicator 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3d6163b7499f9afc436a5b7f11ac3b38e128f6e2f8eb6a37fc6fe6521080e1d
-  data.tar.gz: b2647db6156463d1d06317a3cd82305cd2cf29a464484017e920e653d9db7dcc
+  metadata.gz: b2177b079f5600e5c04e1f1f15ba535838c9acfe7244c0041408bd874f6f02e1
+  data.tar.gz: 823005978281166065bb392f6cee4665bfd4196c181272392b21feac89fd2974
 SHA512:
-  metadata.gz: e4233d02d68f77beec56049b8ab6bb13c93b114b003d57a903b945f29f9caace9dd9e835b0e9bf7baf9a60dd581b8aceadc2b3f3151e49539d1fbce6ebc8c7d9
-  data.tar.gz: a93c002f76da05a95d1d426a8a94db8107b59627217ccf2a4d559a381c941b6d7ea7c1a1ede8e5063aa3c8d2d52b4ce3d8397e77e014dc4b7aeb4626a8f6905f
+  metadata.gz: b0c462b21de4ef04f9bcaf6fb5052a58e913cb4e7a1901acad868e90fb286370874eddfe38112d0aee50bc0a55ae4a09bfa58760e497ffe83f9be4207e5e10d8
+  data.tar.gz: cb9fd8cc76825c0741cd5f568340d8649ce3b6465240805bfd620d92ad1a9d1adcddf1369db1465d9e50907b90607e81fbf9f84fc2b7682fd2cf65a83fbab3e5

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+### Upcoming
+
+* (Nothing yet)
+
+
+### 2.0.0 / 2026-10-24
+
+A rewrite of the gem under its existing name, and a breaking release: the 1.x
+API is gone. The gem now compiles and evaluates the condition language of the
+Elixir reference implementation, [predicator-ex](https://github.com/riddler/predicator-ex),
+with its instruction set version 6, and is checked against that
+implementation's conformance corpus at the tag `v9.5.0`, vendored under
+`conformance/` (`conformance/SOURCE.json` records the tag, its commit and the
+corpus hash). It claims tier 9 of the corpus's evaluator surface and tier 7 of
+its compiler surface (`conformance/registry.json`), with no case skipped. It
+requires Ruby 3.3 or later and has no runtime dependencies. To stay on 1.x,
+pin `gem "predicator", "~> 1.2"`; the README's "Upgrading from 1.x" maps each
+1.x call to its 2.0 counterpart. The 1.x history, and the source of the 1.x
+gem, live in the [riddler/predicator](https://github.com/riddler/predicator)
+repository (`impl/rb`).
+
+**Added**
+
+* The value domain: `Predicator::UNDEFINED` (an absence, distinct from `nil`, which is null), and the immutable values `Predicator::Date`, `Predicator::DateTime` (an instant in UTC to the microsecond) and `Predicator::Duration` (eight integer units). Integers and floats stay Ruby's `Integer` and `Float`, so `1` and `1.0` stay distinct.
+* The error values `Predicator::ParseError`, `Predicator::EvaluationError`, `Predicator::TypeMismatchError` and `Predicator::UndefinedVariableError`, each with a `type` and a `reason`, a `message`, and a `Predicator::Position` (line and column) where one is known; and `Predicator::Error`, the exception that carries one.
+* `Predicator::Result`, the value a call answers: `ok?`, `value` and `error`.
+* `require "predicator/tagged"` loads `Predicator::Tagged`, a codec for the conformance corpus's tagged JSON encoding: `decode("[1.0]")` and `encode([1.0])` answer a `Predicator::Result`, and `decode!` and `encode!` raise `Predicator::Error` instead.
+* `Predicator.compile(source)` compiles an expression to the instruction list the evaluator runs, and `Predicator.compile_program(source)` compiles one or more statements (assignments, `if`, `while`, expressions) separated by `;`. Each answers a `Predicator::Result`: the list, its operands predicator values (`Predicator.compile("x > 1").value` is `[["load", "x"], ["lit", 1], ["compare", "GT"]]`), or a `Predicator::ParseError` with its reason, message and position. A source that is not a String, or not valid text in its encoding, raises `ArgumentError`.
+* A decimal literal too large for a finite Float is refused with the reason `number_out_of_range`, and compiling any source prints no warning.
+* `Predicator.evaluate(program, context, **options)` runs an expression, given as an instruction list or as source text, and answers its value; `Predicator.execute` runs a statement program and answers the context at halt; `Predicator.execute_value` answers the pair of the last expression statement's value and that context. A run that stops answers its error value and no context.
+* `Predicator.parse(source)` answers an expression's syntax tree (its node classes are private and its shape is not a compatibility promise), `Predicator.parse_duration("1h30m")` answers a `Predicator::Duration` or an `EvaluationError` with the reason `invalid_duration_format`, and `Predicator.isa_version` answers 6.
+* Every entry point that answers a `Predicator::Result` has a bang variant (`compile!`, `compile_program!`, `evaluate!`, `execute!`, `execute_value!`, `parse!`, `parse_duration!`) that answers the value or raises `Predicator::Error` carrying the error value.
+* A run's options are keywords of the call: `functions:` (a Hash of String name to a callable, called with the arguments only, each a copy, refusing by raising), `clock:` (a callable answering a `Predicator::DateTime`; one that answers anything else, or raises, fails the run with an `EvaluationError` whose reason is `clock_failed`), `on_unbound:` (`:undefined` or `:error`) and `loop_budget:` (10000 back edges by default). Nothing is configured globally.
+* A context, a literal operand or a host function's answer outside the value domain (a key that is not a String at the context's root, a Symbol or other object, a Float that is not finite, a list or map that contains itself or nests past 100 levels) fails the run with an `EvaluationError` (`unsupported_host_value`, `non_finite_number`, `cyclic_value`, `depth_limit_exceeded`) instead of raising.
+
+**Changed**
+
+* Breaking: Ruby 3.3 or later is required, where 1.x declared no Ruby version; stay on 1.x on an older Ruby.
+
+**Removed**
+
+* Breaking: the 1.x API is removed, and 1.x code does not run against 2.0. Pin `gem "predicator", "~> 1.2"` to stay on 1.x, or move each call as the README's "Upgrading from 1.x" says; store a condition's source text and compile it with 2.0 rather than reusing a 1.x instruction list.

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 JohnnyT
+Copyright (c) 2016-2026 JohnnyT
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,78 +1,354 @@
-[![Gem Version](https://badge.fury.io/rb/predicator.svg)](http://badge.fury.io/rb/predicator)
-[![Build Status](https://travis-ci.org/predicator/predicator.svg?branch=master)](https://travis-ci.org/predicator/predicator)
-[![Coverage Status](https://coveralls.io/repos/github/predicator/predicator/badge.svg?branch=master)](https://coveralls.io/github/predicator/predicator?branch=master)
-
 # Predicator
 
-Predicator is a safe (does not eval code), admin or business user facing predicate engine. It turns a string predicate like `"score > 600 or (score > 580 and monthly_income > 9000)"` along with a supplied context into a `true` or `false`. This predicate can be stored as an attribute of a model (ex: an Offer model could store a predicate indicating if it is available to a customer).
+[![MIT License][badge_license_url]](LICENSE)
+[![CI][badge_ci_url]](https://github.com/riddler/predicator-rb/actions/workflows/ci.yml)
+[![Gem Version][badge_version_url]](https://rubygems.org/gems/predicator)
+
+A safe, non-evaluating condition language for end users, for Ruby. A condition
+is written as text, such as `score > 85 and 2 in items`, compiled to a flat
+list of stack-machine instructions and run against a context of variables. No
+Ruby is ever evaluated: the text is read by a lexer and a parser of this
+package, and the instructions are run by an evaluator that can do only what
+the instruction set says. The language, the instruction set and the answers
+are wire-compatible with the Elixir reference implementation,
+[predicator-ex](https://github.com/riddler/predicator-ex), and the gem is
+checked against that implementation's conformance corpus.
+
+## Why Predicator
+
+A rule an end user writes has to be decided by code the user did not write,
+and often in more than one place. Passing the text to `eval` hands the user
+the whole interpreter; a hand-rolled parser per place lets the copies drift
+apart. Predicator gives one small language with a defined set of operations,
+a defined answer for every operand a rule can meet (an error value, never a
+crash), and a shared corpus that every implementation of it must pass. A
+condition compiled in one implementation can be run by another, because the
+instruction list is plain data.
 
-## Usage
+## Install
 
-Simple usage:
+Add `predicator` to your Gemfile:
+
+```ruby
+gem "predicator", "~> 2.0"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install predicator
+
+## Basic usage
 
 ```ruby
 require "predicator"
 
-Predicator.evaluate "score > 600 or (score > 580 and income > 9000)", score: 590 # false
+# Compile once: the instruction list is plain data you can store or send
+compiled = Predicator.compile("score > 85 and 2 in items")
+compiled.value
+# => [["load", "score"], ["lit", 85], ["compare", "GT"], ["jump_if_falsy_or_pop", 4],
+#     ["lit", 2], ["load", "items"], ["in"]]
+
+# Run it against a context: a Hash keyed by Strings
+context = { "score" => 90, "items" => [1, 2, 3] }
+Predicator.evaluate(compiled.value, context).value   # => true
+
+# Or hand evaluate the source and let it compile
+Predicator.evaluate("a.b + 1", { "a" => { "b" => 2 } }).value   # => 3
+
+# A statement program answers the context it leaves
+Predicator.execute("x = 1; y = x + 2").value        # => {"x" => 1, "y" => 3}
 
-Predicator.evaluate "score > 600 or (score > 580 and income > 9000)", score: 590, income: 9500 # true
+# A host function is passed per call, by name
+double = ->(n) { n * 2 }
+Predicator.evaluate("double(x)", { "x" => 4 }, functions: { "double" => double }).value   # => 8
+
+# The bang variants answer the value itself, or raise Predicator::Error
+Predicator.evaluate!("score > 85", { "score" => 90 })   # => true
 ```
 
-Example usage with a model:
+## The result and error values
+
+Every entry point answers a `Predicator::Result`: `ok?`, `value` and `error`.
+A successful result has `error == nil` and a failed one has `value == nil`, so
+read `ok?` and not the value: `nil` is predicator's null, and a successful
+result may hold it. Nothing about the source or the program raises: a source
+that does not compile, a run that stops and a value outside the language's
+domain all answer a failed result.
 
 ```ruby
-class Customer
-  ...
-  def to_hash
-    {
-      ...
-      score: score,
-      income: income,
-      ...
-    }
-  end
-end
-
-class Offer
-  attr_accessor :available_predicate
-  
-  ...
-  
-  def available_to? customer
-    Predicator.evaluate available_predicate, customer.to_hash
-  end
-end
+result = Predicator.evaluate("x / 0", { "x" => 1 })
+result.ok?                 # => false
+result.error.type          # => "EvaluationError"
+result.error.reason        # => "division_by_zero"
+result.error.message       # => "divide was given a zero divisor"
 ```
 
-## Installation
+A call that compiles or runs answers one of four error values, each with a
+`type` (its class's name), a `reason`, a `message` and a `position` (a
+`Predicator::Position` with `line` and `column`, or `nil` where none is
+known):
+
+- `Predicator::ParseError`: a source that does not compile. It always has a
+  position.
+- `Predicator::EvaluationError`: a run that stopped, such as a division by
+  zero, an unknown instruction or a host function that raised.
+- `Predicator::TypeMismatchError`: an operand an operation refused on its
+  type. Its reason is the operation.
+- `Predicator::UndefinedVariableError`: a variable the context does not bind,
+  when the run's answer depends on it.
+
+The `type` and the `reason` are what the conformance corpus matches; the
+`message` is for a person and may change. Each entry point has a bang variant
+(`compile!`, `compile_program!`, `evaluate!`, `execute!`, `execute_value!`,
+`parse!`, `parse_duration!`) that answers the value or raises
+`Predicator::Error`, whose `error` is the same error value.
+
+Two things still raise. A bug in the call itself (an argument of the wrong
+kind, an unknown option, a source that is not valid text) raises
+`ArgumentError`. And an exception that is not a `StandardError` (an
+`Interrupt`, a `SystemExit`, a `NoMemoryError`) raised by host code a run
+calls propagates unchanged.
+
+### The entry points
+
+| Call | Answers, in the result |
+|---|---|
+| `Predicator.compile(source)` | the instruction list of an expression, or a `ParseError` |
+| `Predicator.compile_program(source)` | the instruction list of one or more statements separated by `;`, or a `ParseError` |
+| `Predicator.evaluate(program, context = {}, **options)` | an expression's value; `program` is an instruction list or source |
+| `Predicator.execute(program, context = {}, **options)` | the context at halt, a Hash holding every write; the context passed is never changed |
+| `Predicator.execute_value(program, context = {}, **options)` | the pair `[value, context]` of the last expression statement's value and the context at halt |
+| `Predicator.parse(source)` | the root of the syntax tree |
+| `Predicator.parse_duration(text)` | a `Predicator::Duration` read from text such as `"1h30m"` |
+| `Predicator.isa_version` | the instruction-set version the build emits and runs, 6 |
+
+`parse` answers the syntax tree's root. The node classes and the tree's shape
+are not part of the public surface and may change in a minor version.
+
+### Options
 
-Add this line to your application's Gemfile:
+The options of a run are keywords of the call that runs it. Nothing is
+configured globally.
+
+- `functions:` a Hash of String name to a callable, the host's functions for
+  this run. A function is called with the call's arguments only, first
+  argument first, and nothing else (no context argument). Each argument is a
+  copy, so nothing the function does to one changes the context. The counts of
+  arguments a function takes are read from its parameters. It refuses by
+  raising a `StandardError`, which fails the run with an `EvaluationError`. Its
+  answer is checked against the value domain, and an answer outside it fails
+  the run; the answer is not copied. A name here shadows the library function
+  of the same name, for this run only. `{}` by default.
+- `clock:` a callable answering the current time as a `Predicator::DateTime`,
+  read at most once per run and only when the program reads the time. The
+  system's real-time clock by default. A clock that answers anything else, or
+  raises a `StandardError`, fails the run with the reason `clock_failed`.
+- `on_unbound:` what a load of a variable the context does not bind does:
+  `:undefined` (the default) pushes `Predicator::UNDEFINED` and fails the run
+  with an `UndefinedVariableError` only if undefined is the answer; `:error`
+  fails the run at the load.
+- `loop_budget:` how many back edges one run may take, an Integer of at least
+  0, 10_000 by default. A run that finds it spent fails with the reason
+  `loop_budget_exceeded`.
+
+A run that stops answers its error value and no partial context: `execute` and
+`execute_value` answer neither a context nor a value for a run that stopped.
+
+### The value domain
+
+A context, and any literal operand of an instruction list you built, is
+checked against the value domain before anything runs. The domain is Ruby's
+own values where they fit: `nil` (null), `true` and `false`, `Integer` and
+`Float` (kept apart, so `1` and `1.0` differ), `String`, `Array` (a list) and
+`Hash` (a map, keyed by a String, an Integer, `true`, `false`, `nil` or
+`Predicator::UNDEFINED`), plus `Predicator::UNDEFINED` (an absence, distinct
+from `nil`), `Predicator::Date`, `Predicator::DateTime` (an instant in UTC to
+the microsecond) and `Predicator::Duration` (eight integer units).
+
+The root keys of a context are Strings: a Symbol key at the root fails the run
+with an `EvaluationError` (reason `unsupported_host_value`) and is not
+converted. The same reason refuses a value the domain has no member for (a
+Symbol, a `Time`, any other object). A Float that is not finite
+(`non_finite_number`), a list or map that contains itself (`cyclic_value`) and
+lists and maps nested past 100 levels (`depth_limit_exceeded`) are refused the
+same way. Equality, ordering and membership walk nested lists and maps without
+recursing, so a value nested to any depth inside those limits is compared
+without overflowing the stack.
+
+`require "predicator/tagged"` loads `Predicator::Tagged`, a codec for the
+conformance corpus's tagged JSON encoding, which keeps what a JSON round trip
+loses (dates, instants, durations, undefined): `decode` and `encode` answer a
+`Predicator::Result`, and `decode!` and `encode!` raise `Predicator::Error`.
+A failed codec result carries a `Predicator::Tagged::CodecError`, which has a
+`type`, a `reason` and a `message` and no position.
+
+## Compatibility
+
+- **Ruby 3.3 or later** (`required_ruby_version` in the gemspec). CI runs the
+  test suite on every Ruby minor from 3.3 up to the version `mise.toml` pins,
+  and the full quality gate on that pinned version.
+- **No runtime dependencies.** The gemspec declares none; `strscan` and `json`
+  are default gems that ship with Ruby.
+- **No shared mutable state.** There is no global configuration, no monkey
+  patch and no class-level or module-level mutable state. Host functions and
+  clocks are passed per call, and a call reads only its arguments, so nothing
+  is shared between calls.
+- **Instruction set:** version 6, answered by `Predicator.isa_version`.
+
+## Conformance
+
+The language is defined by the reference implementation's conformance corpus,
+vendored under `conformance/` at a release tag of
+[predicator-ex](https://github.com/riddler/predicator-ex). `conformance/SOURCE.json`
+names the tag, the commit and the corpus hash; at this head they are the tag
+`v9.5.0`, the commit `fd7fb0157e5a314086197187b4c5192bae31720e`, the
+instruction-set version 6 and the hash
+`sha256:ddc5cf824b06b4899e1bd4166263a1ee07016ff239216e029b9276ac17243975`.
+
+The corpus has two surfaces: the **evaluator** runs an instruction list against
+a context, and the **compiler** compiles a source to the instruction list the
+corpus expects. Cases are grouped in nine cumulative tiers, and a claim of
+tier N says every case of that surface in tiers 1 through N passes.
+`conformance/registry.json` records the claims and one entry per passing case.
+At this head:
+
+- The evaluator claims tier 9, with 262 entries. The corpus holds 267 evaluator
+  cases; the other 5 carry the `retired` feature tag (they use an opcode the
+  instruction-set version 6 retired), and a run that claims version 6 does not
+  attempt them.
+- The compiler claims tier 7, with 220 entries: every compiler case in the
+  corpus, all of them in tiers 1 through 5 and 7. A case with no source text
+  is not on the compiler surface.
+
+No case is skipped. A case this package cannot pass is a defect to bring to
+the reference, never an entry on a skip list. The counts are read from the
+registry and the corpus, and you can re-derive them: the registry's `claims`
+array and its `entries` (each `{case_id, surface, tier}`) hold the claims and
+the passes, `conformance/manifest.json` holds the case count of each tier, and
+`mise exec -- bundle exec rake registry` re-runs both surfaces and prints, per
+surface, how many cases of the corpus have no entry (0 of 220 for the compiler,
+5 of 267 for the evaluator at this head). `mise exec -- bundle exec rake` runs
+the whole gate, which includes that check and fails if the registry and a run
+made now disagree.
+
+### Differences from the reference
+
+Where the corpus is silent, the reference at the tag answers. These are the
+places where this package's answer follows the reference's normative text
+rather than its code, follows its code where its text is silent, or has no
+counterpart in the reference:
+
+- **A duration is the map of its eight units, from any origin.** The
+  reference's instruction-set document (`docs/isa.md`, section 3) makes a
+  duration a map of its eight units, `years` through `milliseconds`. A
+  duration here reads and moves as that map whether it came from a literal, an
+  opcode or the host: its unit names are its keys and any other key misses. A
+  plain map handed where a duration is read (a relative date's operand) is
+  read the same way, with an absent unit as 0.
+- **Bracket access on a date or an instant** follows the reference's code,
+  which its instruction-set prose does not state: a `Predicator::Date` or
+  `Predicator::DateTime` takes a bracket access as a map would. A key that can
+  be a map key (a String, an Integer, a boolean, null or undefined) misses and
+  answers undefined; any other key is a `TypeMismatchError`.
+- **A Float result that is not finite** (an overflow) is refused as an
+  `EvaluationError` with the reason `non_finite_number`. The reference has no
+  answer of its own there to follow.
+- **A store through a date or an instant** is refused with the reason
+  `not_a_container`. **A store through a duration** writes through the plain map
+  of its eight units, the same reading the `object_set` instruction uses.
+- **The parser bounds nesting.** The reference's parser has no bound. This
+  parser refuses a source that nests 400 levels or more (the whole expression
+  counts as the first level), with the reason `nesting_depth_exceeded`. On a
+  stack too small to reach that limit, as a Fiber's default stack is (each
+  request of an asynchronous server runs in one), the parser refuses at a
+  lower depth under the same reason rather than raising `SystemStackError`.
+  The emitter has the same refusal for a tree whose walk runs out of stack.
+- **The host function contract is arguments only.** The reference passes a
+  function its arguments and the context, and takes an ok or error tuple. Here
+  a function takes the arguments, answers its value and refuses by raising.
+- **The options differ.** The reference's `protected_roots` option (roots a
+  statement program may not store into) is not offered, nor are its
+  `providers`, `builtins`, `host`, `positions` and `segment_positions`
+  options; an unknown keyword raises
+  `ArgumentError`. `functions:`, `on_unbound:` and `loop_budget:` are in both.
+  `clock:` is this package's own: the reference reads the system clock, and
+  here the host passes one per call.
+
+## Upgrading from 1.x
+
+Version 2.0.0 is a different implementation under the same gem name. It is a
+breaking release, not an upgrade path for 1.x code, and the 1.x API is gone.
+To stay on 1.x, pin it (1.x releases stay installable from rubygems.org; the
+last is 1.2.1):
 
 ```ruby
-gem "predicator"
+gem "predicator", "~> 1.2"
 ```
 
-And then execute:
+The 1.x source lives in the
+[riddler/predicator](https://github.com/riddler/predicator) repository under
+`impl/rb`. To move to 2.0:
 
-    $ bundle
+| 1.x | 2.0 |
+|---|---|
+| `Predicator.evaluate(source, context = {})` answered the value | `Predicator.evaluate(source, context)` answers a `Predicator::Result`; `evaluate!` answers the value and raises `Predicator::Error` |
+| `Predicator.compile(source)` answered an instruction list | `Predicator.compile(source)` answers a `Result` holding an instruction list; `compile!` answers the list |
+| `Predicator.evaluate_instructions(instructions, context)` | gone: `Predicator.evaluate(instructions, context)` takes an instruction list or source |
+| `Predicator.parse(source)` answered a `Predicator::AST` node with `to_instructions`, `to_s`, `to_dot` and `Enumerable` | `Predicator.parse(source)` answers a `Result` holding the tree's root; its node classes and shape are not public, and the node methods and the visitors are gone |
+| `Predicator::Parser`, `Predicator::Evaluator` (with `stack` and `result`), `Predicator::Context` and `Predicator::AST` | gone: they are private to the package, and a context is a plain Hash |
+| a source that did not parse raised from the parser | a source that does not compile answers a failed `Result` with a `ParseError` |
+| a context given as a Hash with String or Symbol keys, or as keywords (`evaluate "score > 1", score: 2`) | a Hash passed as the second argument, keyed by Strings; a Symbol key at the root fails the run with `unsupported_host_value`, and keywords are the run's options |
+| a variable the context did not bind read as `nil`, so a comparison with it answered `false` | the run's answer is undefined, and fails with an `UndefinedVariableError` when undefined is the answer; `on_unbound: :error` fails at the load |
+| 1.x instruction lists | a list that uses an opcode 2.0 does not have (such as `jfalse`, `to_int` or `array`) fails with `unknown_instruction`; a list of only `lit`, `load`, `not` and `compare` runs, under 2.0's rules for the comparison and the unbound variable above; recompile the source with 2.0 either way |
+| a custom function, a clock or a limit: none | `functions:`, `clock:`, `on_unbound:` and `loop_budget:` keywords |
+| statement programs: none | new in 2.0: `compile_program`, `execute` and `execute_value` |
 
-Or install it yourself as:
+Store the condition's source text, not its 1.x instruction list, and compile
+it with 2.0. The instruction list 2.0 emits is the reference's instruction set
+version 6, which is the same plain data in every implementation of it.
 
-    $ gem install predicator
+## Documentation
 
-## Development
+- Look up
+  - Every public method and class carries a YARD doc comment in `lib/`:
+    the `Predicator` module's entry points, the values, the error values and
+    `Predicator::Result`, and `Predicator::Tagged`.
+  - [The instruction-set reference](https://github.com/riddler/predicator-ex/blob/v9.5.0/docs/isa.md):
+    the instructions, the value space and the refusals, which this package
+    implements, read at the corpus tag.
+  - [The changelog](CHANGELOG.md): what changed in each version.
+  - [The conformance corpus](conformance/README.md): what is vendored, from
+    where, and what is this repository's own.
+- Understand
+  - [Why a predicate language of its own](https://github.com/riddler/predicator-ex/blob/v9.5.0/docs/explanation/why-a-predicate-language-of-its-own.md):
+    why not `eval`, and why not a general-purpose language.
+  - [Embedding Predicator](https://github.com/riddler/predicator-ex/blob/v9.5.0/docs/guides/embedding.md)
+    and [custom functions](https://github.com/riddler/predicator-ex/blob/v9.5.0/docs/guides/custom-functions.md),
+    in the reference's terms (read the function contract above for this
+    package's).
 
-After checking out the repo, run `bin/setup` to install dependencies.
-Then, run `rake test` (or just `rake`) to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Development
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+```bash
+mise install                          # the Ruby that mise.toml pins
+mise exec -- bundle install           # the dev tools
+mise exec -- bundle exec rake         # the gate: rubocop, the corpus and registry checks, the tests
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/predicator/predicator.
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/riddler/predicator-rb.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+MIT, see `LICENSE`.
+
+<!-- BADGES -->
+[badge_license_url]: https://img.shields.io/badge/license-MIT-brightgreen.svg?cacheSeconds=3600?style=flat-square
+[badge_ci_url]: https://github.com/riddler/predicator-rb/actions/workflows/ci.yml/badge.svg
+[badge_version_url]: https://badge.fury.io/rb/predicator.svg