One rule language for every programming language and operating system

This page explains how Rule Cascade gives the same answer in every language and on every operating system, which form of the engine to use where, and how to add a language that has no runtime yet.

• The design in one paragraph
• What exists today
• Choosing a form
• Why engines disagree, and how each cause is closed
• Operating systems
• Using a language that has no runtime
• Writing a runtime for a new language
• Compatibility promises

The design in one paragraph

Rules are data: a JSON value with a fixed grammar, written in YAML or JSON. A compiler checks a ruleset once and seals it into a bundle, which is plain JSON. An evaluator is a small pure function from (manifest, request) to a result; it needs a JSON parser, decimal arithmetic and a regular-expression engine, and nothing from the operating system. The meaning of every operator is written down in the specification to the level where two implementations cannot reasonably differ, and a conformance suite of hand-written cases and seeded random requests is run against every engine on Linux, Windows and macOS. An engine that disagrees with the suite is wrong by definition and does not ship.

Three decisions make this work:

1. JSON is the only interchange format. YAML is for authors. Nothing that evaluates ever reads YAML, so no evaluator depends on a YAML library or on how one reads no or 012.
2. Compile once. Schema validation, inheritance, override policies and the static checks run in one place, usually CI. What ships is the result. A new language therefore needs only an evaluator, which is a few hundred lines, to take part.
3. The suite is the product. The Python package is the reference implementation, but what binds a runtime is the suite. Every difference ever found between two engines became a case in it.

What exists today

The evaluator alone (values, patterns, expressions, evaluation) is about 700 lines in Python and 900 in TypeScript. That is the size of the job for a new language.

The command and the WebAssembly module are the same Go code as the library. They exist so that a language without a runtime is not a language without Rule Cascade: see Using a language that has no runtime.

Choosing a form

In every row the rules, the bundle and the answer are the same. Mixing forms is normal: a React front end, a Spring Boot API and a C# back-office tool can evaluate the same bundle.

Custom operators (x-*) are host code and exist only in the native libraries. A ruleset that must run through the command, the module or the rule server should use functions instead, or keep the rules that need a custom operator enforcement: server in a service that has a native runtime.

Why engines disagree, and how each cause is closed

Each row is a way two correct-looking implementations give different answers. The right-hand column is the rule that removes the difference; the section numbers refer to the specification.

Operating systems

The engine has no operating-system surface: no files, no clock, no network, no environment. What varies between systems is therefore only how an engine is delivered and started.

sh packages/go/scripts/build-all.sh builds the six commands and the module and writes their SHA-256 checksums. CI runs the complete conformance suite against each runtime on Linux, Windows and macOS, both in process and over the engine protocol.

Things that are easy to get wrong on one system only, and what the project does about them:

• Text mode on Windows. An engine writes \n; a client must read lines in UTF-8 and tolerate \r\n. The conformance driver does, and the protocol says a carriage return before the line feed is tolerated in requests.
• Console code pages. The engine protocol is UTF-8 whatever the console is set to. The Java engine sets the encoding of its streams explicitly for this reason.
• Git line endings. .gitattributes keeps every text file as LF, so the embedded schema copies are byte-identical on every checkout.
• Path separators and globbing. The commands take forward slashes on every system; shells that do not expand *.ruleset.yaml (PowerShell, cmd) need the files listed.

Using a language that has no runtime

Start the command once and exchange lines of JSON with it. This is the whole protocol (specification section 13):

→ {"command":"load","bundle":{ ...the bundle... }}
← {"ok":true,"result":{"ruleset":"acme.payments.transfer","version":"1.0.0","checksum":"sha256:c192...","channels":["client","server"],"missingOperators":[]}}
→ {"command":"evaluate","ruleset":"acme.payments.transfer","request":{"entity":"Transfer","operation":"create","data":{...}}}
← {"ok":true,"result":{"decision":"deny","findings":[...],"effects":[...],"commands":[]}}

load also takes a single manifest ("manifest":{...} in place of "bundle"). A front end that must not hold the bundle loads the client manifest that way; channels is then ["client"], and a request for the other channel is answered with CHANNEL_UNAVAILABLE.

examples/engine-clients has the same client in Python, Node.js, Ruby, PHP, Java, shell, Rust, C# and PowerShell, each under 130 lines, and two that load the WebAssembly module in process. They all print the same output, and CI runs them.

Keep one engine process alive for the life of your program. Measured on a two-core virtual machine, an evaluation through the command takes about 0.14 ms once the bundle is loaded; starting a process per request costs about 3.4 ms. One process answers requests in order, so start several for parallelism.

Writing a runtime for a new language

Do this when a language is used enough in your organisation to deserve in-process evaluation, or when it must supply custom operators.

1. Start at the evaluator level. Read a bundle, evaluate. Leave the compiler to the command.

2. Port in this order, running the suite after each step:

   1. values: equality, canonical JSON, rendering, number rounding (values.py);
   2. the portable-pattern scanner and its translation to your regular-expression engine;
   3. expressions (expressions.py), until conformance/expressions.json passes;
   4. evaluation (evaluate.py), until the golden tests and conformance/evaluations.json pass.

3. Speak the engine protocol (engine.py is 175 lines) and let the shared driver judge:

   python tools/rulecheck.py conformance --engine "your-engine engine --conformance-operators"

   An evaluator answers compile with UNSUPPORTED; the driver skips the compiler cases.

4. Add the compiler level only if you need it: schema validation (a small interpreter of the schema file is easier to keep right than a hand-written mirror), inheritance, static checks, checksum. conformance/load-errors.json and rulesets.json cover it.

5. Fuzz against the reference. The suite's 1000 seeded random requests (conformance/evaluations.json, generated by rulecheck sync) are a start; generate more of your own and compare your engine's answers with the Python reference. The runtimes in this repository were compared that way, at a much larger scale, while they were written, and the differences found are now cases in the suite. The scripts for those larger runs are not in this repository, so that part is a record of how the ports were built, not a check anyone can repeat.

What each language needs to bring:

Compatibility promises

• The specification version (ruleCascade: 1.x) and the bundle format version (ruleCascadeBundle: 1.x) only add within a major version. A runtime rejects a major version it does not implement instead of guessing.
• The meaning of an operator never changes. New operators arrive in a new profile.
• A bundle is immutable. Its checksum identifies the exact rules; every evaluation result carries it, so a decision can be traced to the rules that made it, in whatever language it was made.
• Before 1.0 the specification is a draft and may still change between alpha versions. Every change is recorded in the changelog.

Rendered from docs/languages.md in the repository. Edit it there.