Rule Cascade
Reference

Changelog

All notable changes are recorded here. The format follows Keep a Changelog and the project uses Semantic Versioning.

All notable changes are recorded here. The format follows Keep a Changelog and the project uses Semantic Versioning.

[Unreleased]

Changed

  • Rule Cascade has its own domain: https://rulescascade.com. The documentation, the downloads, install.sh and install.ps1 are served there; rules.sdods.com redirects every path to the same path on the new domain, so existing links and scripts keep working.
  • The Go module is rulescascade.com/go (go install rulescascade.com/go/cmd/rcas@latest). Versions up to 1.0.0-alpha.5 remain available as rules.sdods.com/go; to move, replace the import path and require 1.0.0-alpha.6 or later.
  • The schema $id is https://rulescascade.com/schema/v1/rule-cascade.schema.json. The old address redirects to it.
  • Java coordinates. The Java runtime is com.rulescascade:rules-cascade-core and its package is com.rulescascade (was com.sdods.rules:rules-cascade-core, com.sdods.rules.cascade). It had not been published to Maven Central under the old name.
  • The site tells search engines that rulescascade.com is the canonical address (canonical links, sitemap.xml, robots.txt).

[1.0.0-alpha.5] - 2026-10-06

Added

  • Java on Maven Central: com.sdods.rules:rules-cascade-core, signed with the release key EA4FA781CD906ED62FB1C8341C70DE86DB43612C.
  • Signed downloads on the site: rules.sdods.com/download/, install.sh and install.ps1 serve the signed rcas files, starting with 1.0.0-alpha.4.

Fixed

  • npm ci in a checkout: the repository no longer declares the @rules-cascade/cli-* platform packages; the release adds them to the published @rules-cascade/cli at its exact version.

[1.0.0-alpha.4] - 2026-10-06

Changed

  • Java coordinates. The Java runtime is com.sdods.rules:rules-cascade-core and its package is com.sdods.rules.cascade (was io.github.yarlisaisolutions:rule-cascade-core, io.github.yarlisaisolutions.rulecascade). It had not been published to Maven Central under the old name.

Fixed

  • npx -y @rules-cascade/cli <command> runs rcas. In 1.0.0-alpha.3 the package declared two commands, and npx could not tell which to run, so MCP configurations that start the server with npx failed. The npm package now provides rcas only; the install scripts and go install still provide rule-cascade.

[1.0.0-alpha.3] - 2026-10-06

Added

  • rcas, the Rule Cascade command (it replaces rule-cascade, which stays as an alias): init scaffolds a project (rcas.yaml, a first ruleset with golden tests, CI, a loading guide per language); check and test read the project's rules; compile --all; analyze inventories API schemas and validation code in an existing code base; derive builds baseline rulesets from OpenAPI or JSON Schema (a Go port, byte-identical to the reference); proposals reviews what an agent proposed; doctor; shell completion.
  • AI coding tools. rcas mcp is a Model Context Protocol server whose only write is a proposal under .rcas/proposals/; rcas mcp install registers it with Claude Code, Codex, Cursor, Windsurf, Gemini CLI and VS Code; rcas agent install writes AGENTS.md, CLAUDE.md, GEMINI.md, Copilot and Cursor rules, Claude sub-agents and a skill.
  • Distribution. npm @rules-cascade/cli (with one package per platform), the install scripts https://rules.sdods.com/install.sh and install.ps1, and go install rules.sdods.com/go/cmd/rcas@latest.

Changed

  • The Go module is rules.sdods.com/go, published from the public mirror YarlisAISolutions/rule-cascade-go. The source repository is private; the packages stay free under the Apache License 2.0.
  • Release files are named rcas-<os>-<arch> and rcas.wasm.
  • The schema $id is https://rules.sdods.com/schema/v1/rule-cascade.schema.json.

[1.0.0-alpha.2] - 2026-10-05

The project is now called Rule Cascade. A ruleset is compiled once into a JSON bundle and evaluated identically by Python, TypeScript, Java and Go, by a single-file command for Linux, macOS and Windows, and by a WebAssembly module. The conformance suite has 1899 cases.

Licence

  • Free packages under the Apache License 2.0, Copyright (c) 2026 Yarlis LLC; it replaces the MIT License chosen earlier in this version. LICENSE and NOTICE are in every package (npm, PyPI, the Maven jar under META-INF, the Go module), and every manifest declares Apache-2.0. The source repository is private: the manifests point at https://rules.sdods.com instead of a repository, vulnerabilities are reported to support@sdods.com, and the Go module is published from a public mirror as rules.sdods.com/go.
  • Packages on the public registries. After the signed release, a tag v<version> on main runs the whole CI suite and then publishes to npm and PyPI with trusted publishing, to Maven Central (signed, with sources and javadoc; off until enabled), tags the Go module and pushes a multi-platform server image with a provenance attestation to GHCR. npm packages now publish to npmjs.com instead of GitHub Packages. See docs/releasing.md.

Breaking

  • The npm packages moved to the @rules-cascade scope and split in four. Nothing had been published under the old names. @yarlisaisolutions/rule-cascade is now:

    • @rules-cascade/common: the rule, bundle and manifest types, the cron schedule (@rules-cascade/common/cron) and VERSION. No dependencies.
    • @rules-cascade/core: evaluation and compilation, @rules-cascade/core/loader, and the rule-cascade-node command. It re-exports everything in common, so type imports keep working.
    • @rules-cascade/client: createManifestClient and localStorageAdapter (moved from core), and the React hook at @rules-cascade/client/react (was @yarlisaisolutions/rule-cascade/react).

    @yarlisaisolutions/rule-cascade-server is now @rules-cascade/server. The release publishes them in that order. Java, Python and the server image keep their names. The schema $id is now https://rules.sdods.com/schema/v1/rule-cascade.schema.json, where the site serves it.

  • Name. Rule Contract became Rule Cascade. The document key is ruleCascade (was ruleContract), the schema is spec/v1/rule-cascade.schema.json, the OpenAPI extension is x-rule-cascade, the npm packages are @rules-cascade/common, core, client and server (see the npm entry above), the Maven artifact is rule-cascade-core and the Java package is io.github.yarlisaisolutions.rulecascade.

  • Specification: checksums. The resolved ruleset has the new members types, functions and operators and the renamed key, so the checksum of every ruleset changes.

  • Specification: findings. finding.component is replaced by finding.location, an object with the page, screen, section and component the rule's target names.

  • Specification: patterns. matches accepts only the portable subset of section 4.4. \s and \b, which alpha.1 allowed, are rejected; . matches line breaks; $ is the very end of the string; counts, nested counts multiplied and the pattern length are limited to 1000.

  • Specification: numbers. A JSON number is the IEEE 754 double nearest to what was written, in every runtime. Every number leaving the engine is rounded to 15 significant digits, whether it was computed or passed through. A number beyond the range of a double is refused on the way in and is an evaluation error on the way out.

  • Specification: strictness. An object that is not exactly {var}, {op, args} or {fn, args} is not an expression; an unknown root is null; list indexes are runs of ASCII digits. Dates are written with ASCII digits and nothing after the value, offsets go up to 23:59, and the UTC date lies in the years 0001 to 9999. lower changes only the ASCII letters.

  • Specification: evaluation. A state rule applies all of its effects or none. An evaluation request is shape-checked and refused before anything is evaluated.

  • Specification: YAML. A ruleset in YAML is read by the YAML 1.2 core schema: unquoted no, on and 2026-10-03 are strings. Scalars that YAML 1.1 and 1.2 read differently must be quoted.

  • Tools. rulecheck export and rulecheck corpus are replaced by rulecheck sync. tools/rulecheck.py is no longer the reference implementation; it is the command-line front end of packages/python.

  • Rule server: a token is required (breaking for deployers). The server refuses to start without RULE_SERVER_TOKEN: it logs a fatal line and exits 1 before loading any rules. Set RULE_SERVER_ALLOW_OPEN=1 to serve every endpoint without a token, on a private network only. Embedded, createRuleServer throws unless it is given token or allowOpen: true. The Kubernetes deployment no longer marks the token Secret optional.

  • Specification: patterns. A group that repeats must not contain an unbounded quantifier ((a+)+, (a*){2,}): such a pattern backtracks exponentially and is refused with PATTERN_NOT_PORTABLE. matches refuses a subject longer than 10000 code points with an evaluation error.

  • Specification: nesting depth. An evaluation request whose data, original, actor or ctx is nested more than 64 deep (also every root of env in the expression command) is refused with BAD_REQUEST before anything is evaluated, and a rule expression or function body nested more than 128 deep fails the load with EXPRESSION_TOO_DEEP. Depth is checked before recursing, so no runtime can overflow its stack.

  • TypeScript compiler. Schema validation stops at the first problem (Ajv allErrors: false): reporting every problem took time exponential in expression depth. compile now reports the first schema problem only.

Added

  • Specification: locale fallback. A message is read from the catalog of the requested locale, then from each shorter prefix of the tag (fr-CA, fr), then from the default locale.
  • Specification: one manifest on its own. Every runtime reads a single manifest (RuleSet.from_manifest, fromManifest, FromManifest), which is how a native front end receives rules. In the engine protocol load accepts a manifest, reports channels and missingOperators, and a channel the ruleset lacks is CHANNEL_UNAVAILABLE.
  • Runtimes: start-up check for custom operators. Each runtime reports the custom operators a ruleset needs that the host has not registered.
  • TypeScript: the manifest client keeps working through an outage of the manifest endpoint by returning the cached manifest and reporting that it is stale.
  • Catalog: a server rule protects the credit limit. The read-only state guides the UI; the new validation rule is what stops the change.
  • Specification: targets. A rule may target a page, screen and section in addition to a component and fields, or a semantic data type. Types are declared under types and bound to fields in entities.<Name>.fieldTypes; a rule on a type runs once per bound field with value and field in scope. A request may carry a view that narrows the evaluation to one place.
  • Specification: functions and custom operators. functions declares reusable expressions, called with {fn, args}, with lexical scope and no recursion. operators declares x-* operators that the host supplies; an operator that is missing or fails makes the rule fail closed.
  • Specification: operators. Fifteen core operators: between, mod, abs, min, max, round, upper, trim, concat, substring, text, map, filter, typeOf and yearsBetween. The core profile now has 45.
  • Specification: bundles. A bundle holds the server and the client manifest of a compiled ruleset (section 7). Manifests gained fieldTypes, functions and operators. There are two conformance levels: evaluator and compiler (section 11).
  • Specification: engine protocol. JSON Lines on standard input and output with the commands version, load, manifest, evaluate, expression and compile (section 13).
  • Specification: authoring in YAML (section 12) and the load codes TYPE_UNKNOWN, SCOPE_INVALID, FUNCTION_UNKNOWN, FUNCTION_ARITY, FUNCTION_RECURSIVE, FUNCTION_REDEFINED, OPERATOR_UNDECLARED, FIELD_TYPE_REBOUND, BUNDLE_UNSUPPORTED and BUNDLE_INVALID. The recommended scope levels gained project and module.
  • Evaluation API. GET /rulesets/{rulesetId}/bundle; view in the request and location in a finding; the Bundle and View schemas. The API description is version 1.1.0.
  • Conformance. 499 expression cases (were 147), 191 load-error cases (84), five fixtures with 66 golden tests (two with 17), a 1000-case evaluation corpus (300), the five published bundles, and 88 engine-protocol cases. Two rulesets exist only for the suite: conflicts, ordering and failing closed. Three conformance operators (x-test-reverse, x-test-sum, x-luhn) test the custom-operator mechanism.
  • Python. packages/python, the rule_cascade package: the reference implementation as an installable library, with load, RuleSet.from_bundle, evaluate, evaluate_expression and the engine protocol (python -m rule_cascade engine).
  • TypeScript. Bundles (RuleSet.fromBundle, bundle()), custom operators, view and finding.location, requestProblem and RequestError, missingOperators, patternProblem, jsonFinite, the Engine class and the rule-cascade-node engine command.
  • Java. Bundles (RuleSet.fromBundle, bundle()), CustomOperator, withOperators and requiredOperators, View, and the engine protocol (Engine, Main engine). The schema validator interprets the embedded schema file instead of mirroring it.
  • Go. A new runtime, package rulecascade, at both conformance levels, with no dependencies outside the standard library.
  • Command. rule-cascade, built from the Go runtime: version, check, compile, manifest, evaluate and engine. packages/go/scripts/build-all.sh builds static binaries for Linux, macOS and Windows on amd64 and arm64, with checksums.
  • WebAssembly. The same command as a WASI preview 1 module, rule-cascade.wasm, and packages/go/wasi/run.mjs to run it under Node.js.
  • Rule server. Serves bundles (GET /rulesets/{id}/bundle, behind the token) and loads precompiled *.bundle.json files next to source rulesets. createRuleServer takes custom operators and reports the missing ones; the command logs them at start-up and after a reload.
  • Tools. rulecheck compile writes a bundle. rulecheck conformance --engine "<command>" certifies any engine over the engine protocol. rulecheck sync [--check] regenerates the schema copies, fixtures, bundles, expectations, the evaluation corpus and the example client manifest. rulecheck check reports YAML_NOT_PORTABLE and NUMBER_NOT_PORTABLE.
  • Tools: JSON Logic. rulecheck jsonlogic import|export converts expressions in both directions and refuses what it cannot convert faithfully (docs/json-logic.md).
  • Tools: OpenAPI. rulecheck derive turns the constraints of an OpenAPI component schema into a baseline ruleset with stable finding codes (docs/openapi.md).
  • Examples. A rule catalog by data type and severity (examples/catalog, 34 rules, 25 golden tests); two derived rulesets with their tests (examples/derived); the same two evaluations from Python, Node.js, Ruby, PHP, Java, shell, Rust, C# and PowerShell over the engine protocol, and in process with the WebAssembly module from Node.js and Python (examples/engine-clients). The Spring Boot example can start from a bundle and registers a custom operator.
  • Bindings. The rule-draft response format lists the 45 core operators, function calls, places and types; the evaluate_rules tool accepts a view. bindings/README.md explains both files.
  • CI. Every runtime is built and certified on Linux, Windows and macOS, in process and over the engine protocol. A job cross-compiles the command, certifies the WebAssembly module, runs the engine clients and uploads the binaries. The tools have unit tests (tools/tests).
  • Documentation. docs/authoring-guidelines.md, ADRs 0005 to 0009, packages/python/README.md.
  • Examples: services, batch and agents. examples/backend-node (node:http) and examples/backend-go (net/http) enforce the payments contract the way the Spring Boot example does: evaluate, refuse with 422 problem details, persist, run commands once per idempotency key, and serve the client manifest with an ETag. examples/batch streams a CSV or JSON Lines file through any engine over the engine protocol, one decision per line. examples/agent-tools runs the tools of bindings/llm-tools.json against the rule server, with the actor taken from the session; its README maps the same tools onto MCP.
  • Tests. The React hook and the manifest client of the TypeScript runtime have their own tests. The container smoke test (packages/server/test/smoke-image.sh) also checks that the image fails closed without a token, that a broken reload is refused while the previous rules keep serving, and that SIGTERM drains.
  • Cross-runtime version check. tools/check_versions.py (run by make contract and the CI contract job) fails unless every runtime declares the same version: the TypeScript and server package.json, the Java pom.xml, Go's version.go, and Python's pyproject.toml and __init__.py (PEP 440 1.0.0a2 is read as 1.0.0-alpha.2).
  • CI. One job per new example on Linux, and a job that runs the Go runtime and the Go example on Go 1.22, the minimum go.mod declares, with GOTOOLCHAIN=local so no newer toolchain is used.
  • Rule server: scheduled refresh. RULES_REFRESH=interval (RULES_REFRESH_INTERVAL, at least 1s) or cron (RULES_REFRESH_CRON, RULES_REFRESH_TZ, default UTC) checks the rules directory on a schedule and reloads, with the safety of SIGHUP, only when a file changed. The default, manual, is the previous behaviour. Content that was refused is not retried until it changes.
  • Rule server: cache policy. An optional cache-policy.yaml in the rules directory sets the Cache-Control of client manifests per ruleset: revalidate (default, unchanged), ttl (with stale-while-revalidate and stale-if-error) or permanent. A bad policy file is refused like a bad ruleset. ?checksum= on the manifest URL answers immutable in permanent mode, and 409 with no-store when it is not the checksum being served (a server extension, not in the OpenAPI description). Server manifests and bundles stay private, no-cache.
  • Rule server: worker threads. RULE_SERVER_WORKERS (default 0) evaluates on worker threads with identical results; an evaluation running longer than RULE_EVALUATION_TIMEOUT_MS (default 5000) is answered 503 and its worker replaced. Embedded: workers, evaluationTimeoutMs, operatorsModule and terminateWorkers().
  • TypeScript: manifest caching modes. createManifestClient takes mode (revalidate, ttl, permanent), ttlMs, staleIfError, refreshCron, storage (with localStorageAdapter) and onUpdate; get takes an optional checksum; concurrent requests for one ruleset are shared; refresh() and close(). The default behaviour is unchanged.
  • Refreshing holders. RuleSetHolder (Java, Python) and Holder (Go) reload rules on an interval or a cron schedule, swap them atomically, keep the last good rules on failure and report each refresh to a listener.
  • Cron. One five-field cron syntax in TypeScript (@rules-cascade/common/cron), Java (CronSchedule), Go (ParseCron) and Python (rule_cascade.cron), all tested against tools/cron-cases.json.
  • Benchmarks. make bench measures every runtime on the same bundle and requests (tools/bench-requests.json) and load-tests the rule server with and without workers. docs/performance.md records measured numbers; docs/caching.md describes the caching modes.

Changed

  • Specification. Canonical numbers are exact. abs keeps 34 digits. Members of a protocol request are checked before a ruleset is looked up; optional members may be null.
  • TypeScript, Java. Both runtimes implement the evaluator and the compiler level and are at version 1.0.0-alpha.2.
  • Rule server. POST /evaluations checks the body with the shape check every runtime applies and names the problem in its 400 answer. A ruleset that came from a bundle is listed with its id, version and checksum only. If-None-Match is compared as RFC 9110 says: a list of entity tags, weak or strong, or *. A path with malformed percent-encoding is 400, not 500. A body over the limit is 413 without being read to the end.
  • Tools. tools/lint_specs.py also checks that every pattern in the schema is portable, that the operator list in bindings/ matches the schema, and that all generated files are current.
  • Makefile. make verify also runs the Python package tests, the Go runtime, the release build, every engine over the protocol and the engine clients.
  • Documentation. docs/architecture.md, docs/naming-conventions.md, ADRs 0001 to 0003, CONTRIBUTING.md, SECURITY.md and the deployment notes describe the current design. The README has a table of supported versions (declared minimum, tested in CI, highest observed; no declared maximum) and says what is not verified: the Kubernetes manifests have never been applied, the WebAssembly module has not run in a browser, and the x-rule-cascade binding is checked at lint time only. The claim that the runtimes agree beyond the suite now says which part can be repeated from the repository.

[1.0.0-alpha.1]

Added

  • Specification 1.0 (draft): ruleset schema, normative semantics, evaluation API.
  • Conformance suite: expression cases, load-error cases, fixture checksums and client manifests, golden tests, and a 300-case evaluation corpus.
  • Reference implementation and linter in Python (tools/rulecheck.py).
  • TypeScript runtime for browsers and Node.js, with a React hook and a manifest client.
  • Java runtime with no dependencies.
  • Rule server: stateless HTTP service with health probes, graceful shutdown and safe reload.
  • Examples: organisation and feature rulesets, an OpenAPI binding, a React form, a Spring Boot API.
  • Deployment: Dockerfile and Kubernetes manifests for the rule server.
  • Bindings for OpenAI function tools and structured rule drafting.

Conformance suite

A runtime conforms to Rule Cascade 1.0 when it passes the cases in this directory for the level it claims. Every runtime in this repository runs exactly these files, on every operating system.

On this page

[Unreleased]Changed[1.0.0-alpha.5] - 2026-10-06AddedFixed[1.0.0-alpha.4] - 2026-10-06ChangedFixed[1.0.0-alpha.3] - 2026-10-06AddedChanged[1.0.0-alpha.2] - 2026-10-05LicenceBreakingAddedChanged[1.0.0-alpha.1]Added