rule-cascade 1.0.0a2__py3-none-any.whl

rule_cascade/__init__.py

@@ -0,0 +1,26 @@
+"""Rule Cascade: load, check and evaluate YAML/JSON business rule contracts.
+
+This package is also the reference implementation of the specification. The other runtimes are
+ports of it and must agree with it on every case in the conformance suite.
+
+    from rule_cascade import load, LoadError
+
+    rules = load(document, registry, loader)            # raises LoadError
+    result = rules.evaluate({"entity": "Transfer", "operation": "create", "data": payload})
+    if result["decision"] == "deny": ...
+"""
+from .cron import CronError, CronSchedule
+from .evaluate import ENGINE_ERROR_CODE, ENGINE_ERROR_MESSAGE, RequestError, evaluate, missing_operators, request_problem
+from .expressions import EvalError, evaluate_expression
+from .holder import Reload, RuleSetHolder
+from .ruleset import ChannelError, LoadError, RuleSet, load, manifest, resolve, schema_problems, static_problems
+from .values import canonical, canon_num, equal, plain, render
+
+__version__ = "1.0.0a2"
+__all__ = [
+    "ChannelError", "CronError", "CronSchedule", "ENGINE_ERROR_CODE", "ENGINE_ERROR_MESSAGE", "EvalError", "LoadError",
+    "Reload", "RequestError", "RuleSet", "RuleSetHolder", "canonical",
+    "equal", "missing_operators", "request_problem",
+    "evaluate", "evaluate_expression", "load", "manifest", "plain", "render", "resolve", "schema_problems",
+    "static_problems",
+]

rule_cascade/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .engine import main
+
+sys.exit(main())

rule_cascade/cron.py

@@ -0,0 +1,139 @@
+"""A five-field cron schedule: ``minute hour day-of-month month day-of-week``.
+
+Each field is ``*``, a number, a range ``a-b``, a step ``*/n``, ``a-b/n`` or ``a/n`` (a to the maximum),
+or a comma-separated list of those. Day of week is 0 to 7, where 0 and 7 are both Sunday. Names
+(``JAN``, ``MON``) and macros (``@daily``) are not supported. When day of month and day of week are
+both restricted, a day matches when either matches; a field that begins with ``*`` is not restricted.
+A schedule that can never fire, such as ``0 0 30 2 *``, is refused.
+
+The TypeScript, Java and Go runtimes implement the same semantics; ``tools/cron-cases.json`` is the
+table all four are tested against.
+
+    schedule = CronSchedule("*/5 * * * *")
+    schedule.next(datetime.now(timezone.utc))          # the next fire time, in the zone given
+"""
+import datetime as _dt
+import re
+
+__all__ = ["CronSchedule", "CronError"]
+
+_NAMES = ("minute", "hour", "day of month", "month", "day of week")
+_MIN = (0, 0, 1, 1, 0)
+_MAX = (59, 23, 31, 12, 7)
+_DAYS_IN_MONTH = (31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+_SEARCH_YEARS = 30  # bounds the search for the next fire time; only reachable through a bug
+_DIGITS = re.compile(r"[0-9]+\Z")
+
+
+class CronError(ValueError):
+    """The expression is not a five-field cron schedule this module accepts."""
+
+
+def _digits(text):
+    return min(int(text), 100000)
+
+
+def _field(text, index):
+    name, low, high = _NAMES[index], _MIN[index], _MAX[index]
+    allowed = [False] * (high + 1)
+
+    def number(s):
+        if not _DIGITS.match(s):
+            raise CronError(f"{name}: '{s}' is not a number")
+        n = _digits(s)
+        if n < low or n > high:
+            raise CronError(f"{name}: {n} is outside {low}-{high}")
+        return n
+
+    for part in text.split(","):
+        pieces = part.split("/")
+        if len(pieces) > 2:
+            raise CronError(f"{name}: '{part}' has more than one step")
+        base, step = pieces[0], 1
+        if len(pieces) == 2:
+            if not _DIGITS.match(pieces[1]) or _digits(pieces[1]) == 0:
+                raise CronError(f"{name}: step '{pieces[1]}' is not a positive number")
+            step = _digits(pieces[1])
+        if base == "*":
+            start, end = low, high
+        elif "-" in base:
+            bounds = base.split("-")
+            if len(bounds) != 2:
+                raise CronError(f"{name}: '{base}' is not a range")
+            start, end = number(bounds[0]), number(bounds[1])
+            if start > end:
+                raise CronError(f"{name}: range '{base}' is reversed")
+        else:
+            start = number(base)
+            end = high if len(pieces) == 2 else start  # a/n runs from a to the maximum
+        for v in range(start, end + 1, step):
+            allowed[v] = True
+    return allowed
+
+
+class CronSchedule:
+    """A parsed cron expression. Immutable."""
+
+    def __init__(self, expression):
+        if not isinstance(expression, str):
+            raise CronError("a cron expression is a string")
+        parts = [p for p in re.split(r"[ \t]+", expression.strip()) if p]
+        if len(parts) != 5:
+            raise CronError(f"'{expression}': a cron expression has five fields "
+                            f"(minute hour day-of-month month day-of-week), found {len(parts)}")
+        self.expression = expression
+        self._minutes, self._hours, self._days, self._months, self._weekdays = (
+            _field(p, i) for i, p in enumerate(parts))
+        if self._weekdays[7]:
+            self._weekdays[0] = True
+        self._day_star = parts[2].startswith("*")
+        self._weekday_star = parts[4].startswith("*")
+        if not self._day_star and self._weekday_star:
+            possible = any(self._months[m] and self._days[d]
+                           for m in range(1, 13) for d in range(1, _DAYS_IN_MONTH[m - 1] + 1))
+            if not possible:
+                raise CronError(f"'{expression}' never fires: no chosen month has the chosen days")
+
+    def __repr__(self):
+        return f"CronSchedule({self.expression!r})"
+
+    def _day_matches(self, t):
+        by_day = self._days[t.day]
+        by_weekday = self._weekdays[t.isoweekday() % 7]  # isoweekday: Monday 1 ... Sunday 7
+        return (by_day and by_weekday) if (self._day_star or self._weekday_star) else (by_day or by_weekday)
+
+    def _next_wall(self, after):
+        """The first matching wall-clock minute strictly after ``after`` (a naive datetime)."""
+        t = after.replace(second=0, microsecond=0) + _dt.timedelta(minutes=1)
+        limit = after.year + _SEARCH_YEARS
+        while t.year <= limit:
+            if not self._months[t.month]:
+                t = t.replace(day=1, hour=0, minute=0)  # the day first: 31 January has no 31 February
+                t = t.replace(year=t.year + 1, month=1) if t.month == 12 else t.replace(month=t.month + 1)
+            elif not self._day_matches(t):
+                t = t.replace(hour=0, minute=0) + _dt.timedelta(days=1)
+            elif not self._hours[t.hour]:
+                t = t.replace(minute=0) + _dt.timedelta(hours=1)
+            elif not self._minutes[t.minute]:
+                t += _dt.timedelta(minutes=1)
+            else:
+                return t
+        raise CronError(f"'{self.expression}' does not fire within {_SEARCH_YEARS} years")
+
+    def next(self, after, tz=None):
+        """The first fire time strictly after ``after``, an aware datetime, on the wall clock of ``tz``
+        (default: the zone of ``after``). Seconds are ignored. A wall-clock time that does not exist in
+        the zone (the hour skipped in spring) is skipped; one that happens twice fires once, at the first
+        occurrence. A naive ``after`` is read as UTC."""
+        if after.tzinfo is None:
+            after = after.replace(tzinfo=_dt.timezone.utc)
+        tz = tz or after.tzinfo
+        start = after.replace(second=0, microsecond=0)
+        wall = start.astimezone(tz).replace(tzinfo=None)
+        while True:
+            wall = self._next_wall(wall)
+            first = wall.replace(tzinfo=tz, fold=0)  # fold=0: the earlier of two instants in an overlap
+            if first.astimezone(_dt.timezone.utc).astimezone(tz).replace(tzinfo=None) != wall:
+                continue  # in a gap: the zone never shows this time
+            if first > start:
+                return first

rule_cascade/engine.py

@@ -0,0 +1,218 @@
+"""The engine protocol: JSON Lines over standard input and output (specification section 13).
+
+One JSON object per line in, one per line out, in the same order. It is how a program in any language,
+on any operating system, drives an engine it cannot link to, and how the conformance suite certifies one.
+
+    python -m rule_cascade engine < requests.jsonl
+"""
+import json
+import sys
+
+from . import __version__
+from .evaluate import request_problem
+from .expressions import MAX_VALUE_DEPTH, EvalError, evaluate_expression, too_deep
+from .ruleset import BUNDLE_VERSION, LoadError, RuleSet, load
+
+SPEC_VERSION = "1.0.0"
+
+
+class ProtocolError(Exception):
+    def __init__(self, code, message, **extra):
+        super().__init__(message)
+        self.error = dict(code=code, message=message, **extra)
+
+
+def _need(request, key, kind):
+    value = request.get(key)
+    if not isinstance(value, kind):
+        raise ProtocolError("BAD_REQUEST", f"'{key}' is missing or has the wrong type")
+    return value
+
+
+def _optional(request, key):
+    """An optional object member: absent and null are the same."""
+    value = request.get(key)
+    if value is not None and not isinstance(value, dict):
+        raise ProtocolError("BAD_REQUEST", f"'{key}' must be an object")
+    return value
+
+
+def _not_json(token):
+    raise ValueError(f"{token} is not JSON")
+
+
+def _double(text):
+    value = float(text)
+    if value in (float("inf"), float("-inf")):
+        raise ValueError(f"{text} is outside the range of a double")
+    return value
+
+
+def _whole(text):
+    value = int(text)
+    if abs(value) > 2 ** 53:
+        _double(text)  # beyond 2^53 a whole number is still read; beyond the doubles it is refused
+    return value
+
+
+class Engine:
+    """Holds loaded rulesets between requests. `operators` are the host's custom operators."""
+
+    def __init__(self, operators=None):
+        self.operators = operators or {}
+        self.rulesets = {}
+
+    def _check_source(self, request):
+        """Members first: a malformed request is BAD_REQUEST whatever rulesets are loaded."""
+        if "bundle" in request:
+            _need(request, "bundle", dict)
+        elif "manifest" in request:
+            _need(request, "manifest", dict)
+        else:
+            _need(request, "ruleset", str)
+        channel = request.get("channel")  # optional: absent and null are the same
+        if channel not in (None, "server", "client"):
+            raise ProtocolError("BAD_REQUEST", "'channel' must be server or client")
+        return channel
+
+    def _ruleset(self, request):
+        try:
+            if "bundle" in request:
+                return RuleSet.from_bundle(request["bundle"])
+            if "manifest" in request:
+                return RuleSet.from_manifest(request["manifest"])
+        except LoadError as err:
+            raise ProtocolError("LOAD_FAILED", str(err), problems=err.problems)
+        if request["ruleset"] not in self.rulesets:
+            raise ProtocolError("UNKNOWN_RULESET", f"ruleset {request['ruleset']} has not been loaded")
+        return self.rulesets[request["ruleset"]]
+
+    @staticmethod
+    def _manifest(ruleset, channel):
+        """The manifest to use: the one asked for; by default the server's, or the only one there is."""
+        if channel is None:
+            channel = "server" if "server" in ruleset.channels else ruleset.channels[0]
+        if channel not in ruleset.channels:
+            raise ProtocolError("CHANNEL_UNAVAILABLE", f"ruleset {ruleset.id} was loaded without a {channel} manifest")
+        return channel
+
+    def handle(self, request):
+        """One request object in, one response object out. Never raises."""
+        response = {}
+        try:
+            if not isinstance(request, dict):
+                raise ProtocolError("BAD_REQUEST", "a request is a JSON object")
+            if "id" in request:
+                response["id"] = request["id"]
+            response.update(ok=True, result=self._dispatch(request))
+        except ProtocolError as err:
+            response.update(ok=False, error=err.error)
+        except RecursionError:  # a member nested beyond what the checks before evaluation reach
+            response.update(ok=False, error={"code": "BAD_REQUEST", "message": "a member is nested too deeply"})
+        return response
+
+    def _dispatch(self, request):
+        command = request.get("command")
+        if command == "version":
+            return {"engine": "rule-cascade-python", "engineVersion": __version__, "ruleCascade": SPEC_VERSION,
+                    "bundle": BUNDLE_VERSION, "levels": ["evaluator", "compiler"],
+                    "operators": sorted(self.operators)}
+        if command == "compile":
+            document = _need(request, "document", dict)
+            registry = dict(_optional(request, "registry") or {})
+            schemas = _optional(request, "schemaDocuments")
+            try:
+                meta = document.get("metadata")
+                if isinstance(meta, dict) and isinstance(meta.get("id"), str):
+                    registry.setdefault(meta["id"], document)
+                return load(document, registry, schemas.get if schemas is not None else None).bundle()
+            except LoadError as err:
+                raise ProtocolError("LOAD_FAILED", str(err), problems=err.problems)
+        if command == "load":
+            _need(request, "manifest" if "manifest" in request and "bundle" not in request else "bundle", dict)
+            ruleset = self._ruleset(request)
+            self.rulesets[ruleset.id] = ruleset  # replaces whatever was loaded under that id
+            return {"ruleset": ruleset.id, "version": ruleset.version, "checksum": ruleset.checksum,
+                    "channels": ruleset.channels, "missingOperators": ruleset.missing_operators(self.operators)}
+        if command == "manifest":
+            channel = self._check_source(request)
+            ruleset = self._ruleset(request)
+            return ruleset.manifest(self._manifest(ruleset, channel))
+        if command == "evaluate":
+            channel = self._check_source(request)
+            why = request_problem(request.get("request"))
+            if why:
+                raise ProtocolError("BAD_REQUEST", f"'request': {why}")
+            ruleset = self._ruleset(request)
+            return ruleset.evaluate(request["request"], self._manifest(ruleset, channel), self.operators)
+        if command == "expression":
+            if "expr" not in request:
+                raise ProtocolError("BAD_REQUEST", "'expr' is missing")
+            env, functions = _optional(request, "env"), _optional(request, "functions")
+            for root, value in (env or {}).items():
+                if too_deep(value):
+                    raise ProtocolError("BAD_REQUEST", f"'env.{root}' is nested more than {MAX_VALUE_DEPTH} deep")
+            try:
+                return evaluate_expression(request["expr"], env, functions, self.operators)
+            except EvalError as err:
+                raise ProtocolError("EVALUATION_ERROR", str(err))
+        raise ProtocolError("BAD_REQUEST", f"unknown command {command!r}")
+
+
+    def handle_line(self, line):
+        """One line of text in, one response object out."""
+        try:
+            request = json.loads(line, parse_constant=_not_json, parse_float=_double, parse_int=_whole)
+        except (ValueError, RecursionError) as err:  # RecursionError: nested beyond what the parser handles
+            return {"ok": False, "error": {"code": "BAD_REQUEST", "message": f"not JSON: {err}"}}
+        return self.handle(request)
+
+
+def serve(lines, out, operators=None):
+    """Answer requests until the input ends."""
+    engine = Engine(operators)
+    for line in lines:
+        if not line.strip():
+            continue
+        out.write(json.dumps(engine.handle_line(line), ensure_ascii=False, separators=(",", ":")) + "\n")
+        out.flush()
+
+
+def _luhn(text):
+    if not isinstance(text, str) or len(text) < 2 or not all("0" <= c <= "9" for c in text):
+        return False
+    total = 0
+    for i, c in enumerate(reversed(text)):
+        d = int(c) * (2 if i % 2 else 1)
+        total += d - 9 if d > 9 else d
+    return total % 10 == 0
+
+
+def _reverse(text):
+    if not isinstance(text, str):
+        raise TypeError("x-test-reverse expects a string")
+    return text[::-1]
+
+
+def _sum(*numbers):
+    total = 0.0  # ordinary IEEE 754 doubles, added left to right
+    for x in numbers:
+        if isinstance(x, bool) or not isinstance(x, (int, float)):
+            raise TypeError("x-test-sum expects numbers")
+        total += float(x)
+    return total
+
+
+# The three operators every conformance runner registers (conformance/README.md).
+CONFORMANCE_OPERATORS = {"x-test-reverse": _reverse, "x-test-sum": _sum, "x-luhn": _luhn}
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv or argv[0] != "engine" or set(argv[1:]) - {"--conformance-operators"}:
+        print("usage: python -m rule_cascade engine [--conformance-operators]", file=sys.stderr)
+        return 2
+    sys.stdin.reconfigure(encoding="utf-8")
+    sys.stdout.reconfigure(encoding="utf-8", newline="\n")
+    serve(sys.stdin, sys.stdout, CONFORMANCE_OPERATORS if "--conformance-operators" in argv else None)
+    return 0

rule_cascade/evaluate.py

@@ -0,0 +1,260 @@
+"""Evaluation of one operation on one entity against a manifest.
+
+This module is the executable definition of section 8 of spec/v1/SPECIFICATION.md.
+"""
+import json
+
+from .expressions import FUNCTIONS, MAX_VALUE_DEPTH, OPERATORS, EvalError, boolean, ev, lookup, too_deep
+from .ruleset import PLACEHOLDER, VIEW_KEYS
+from .values import dec, equal, plain, render
+
+ENGINE_ERROR_CODE = "RULE-EVALUATION-ERROR"
+ENGINE_ERROR_MESSAGE = "This rule could not be evaluated."
+
+
+def fill(template, args):
+    return PLACEHOLDER.sub(lambda m: render(args[m.group(1)]) if m.group(1) in args else m.group(0), template)
+
+
+def pointer_path(root, pointer):
+    return root + pointer.replace("/", ".")
+
+
+def set_pointer(obj, pointer, value):
+    *parents, last = pointer.strip("/").split("/")
+    for p in parents:
+        if not isinstance(obj.get(p), dict):
+            obj[p] = {}
+        obj = obj[p]
+    obj[last] = value
+
+
+def _is(kind):
+    return lambda v: v is None or isinstance(v, kind)
+
+
+def _strings(v):
+    return v is None or (isinstance(v, list) and all(isinstance(x, str) for x in v))
+
+
+def request_problem(request):
+    """Why `request` is not an evaluation request, or None. Checked before anything is evaluated,
+    so a malformed request is refused instead of half-evaluated. Optional members may be null."""
+    if not isinstance(request, dict):
+        return "a request is an object"
+    for key in ("entity", "operation"):
+        if not isinstance(request.get(key), str):
+            return f"'{key}' must be a string"
+    for key, ok, what in (("data", _is(dict), "an object"), ("original", _is(dict), "an object"),
+                          ("actor", _is(dict), "an object"), ("ctx", _is(dict), "an object"),
+                          ("view", _is(dict), "an object"), ("resolutions", _is(list), "a list"),
+                          ("trigger", _is(str), "a string"), ("locale", _is(str), "a string")):
+        if not ok(request.get(key)):
+            return f"'{key}' must be {what}"
+    for key in ("data", "original", "actor", "ctx"):
+        if too_deep(request.get(key)):
+            return f"'{key}' is nested more than {MAX_VALUE_DEPTH} deep"
+    if not _strings((request.get("actor") or {}).get("roles")):
+        return "'actor.roles' must be a list of strings"
+    for key in VIEW_KEYS:
+        if not _is(str)((request.get("view") or {}).get(key)):
+            return f"'view.{key}' must be a string"
+    for r in request.get("resolutions") or []:
+        if not (isinstance(r, dict) and isinstance(r.get("rule"), str) and isinstance(r.get("type"), str)
+                and _is(str)(r.get("justification"))):
+            return "a resolution is an object with a string 'rule' and 'type' and an optional string 'justification'"
+    return None
+
+
+def locale_chain(default, wanted):
+    """Catalogs to merge, least specific first: the default locale, then every prefix of the requested
+    tag. `fr-CA` reads en, fr, fr-CA: a regional catalog only needs the messages that differ."""
+    parts = wanted.split("-") if wanted else []
+    return [default] + ["-".join(parts[:i]) for i in range(1, len(parts) + 1)]
+
+
+class RequestError(ValueError):
+    """The evaluation request does not have the shape of specification section 8."""
+
+
+def missing_operators(mf, operators=None):
+    """Custom operators the manifest's rules need that the host has not registered. Check it at start-up:
+    a missing operator does not fail the load, it fails every rule that uses it, closed."""
+    return sorted(name for name in set(mf.get("operators") or []) if not callable((operators or {}).get(name)))
+
+
+def evaluate(mf, request, operators=None):
+    """Pure: no I/O, no clock, no randomness. `operators` maps custom operator names to host functions."""
+    why = request_problem(request)
+    if why:
+        raise RequestError(why)
+    entity, operation = request["entity"], request["operation"]
+    data = json.loads(json.dumps(request.get("data") or {}))  # working copy; compute rules write into it
+    actor = request.get("actor") or {}
+    env = {"data": data, "original": request.get("original"), "actor": actor,
+           "ctx": request.get("ctx") or {}, "params": mf.get("params") or {},
+           FUNCTIONS: mf.get("functions") or {}, OPERATORS: operators or {}}
+    client = mf["channel"] == "client"
+    wanted = ("client", "both") if client else ("server", "both")
+    trigger = request.get("trigger") if client else None
+    view = request.get("view") or {}
+    field_types = (mf.get("fieldTypes") or {}).get(entity, {})
+
+    def selected(r):
+        target = r["target"]
+        return (r.get("enabled", True)
+                and target.get("entity", entity) == entity
+                and operation in r["operations"]
+                and r.get("enforcement", "both") in wanted
+                and (trigger is None or trigger in r.get("triggers", ["submit"]))
+                # a view narrows evaluation to one place in the UI; rules that name no place always apply
+                and all(view.get(k) is None or target.get(k) is None or view[k] == target[k] for k in VIEW_KEYS))
+
+    rules = [r for r in mf["rules"] if selected(r)]
+    messages = mf.get("messages") or {}
+    catalog = {}
+    for locale in locale_chain(mf.get("defaultLocale", "en"), request.get("locale")):
+        catalog.update(messages.get(locale, {}))
+    resolutions = {(x["rule"], x["type"]): x for x in request.get("resolutions") or []}
+    roles = set(actor.get("roles") or [])
+    findings, effects, commands = [], [], []
+
+    def engine_error(rule, err):
+        findings.append({"rule": rule["id"], "code": ENGINE_ERROR_CODE, "severity": "error",
+                         "message": ENGINE_ERROR_MESSAGE, "fields": [], "blocking": True, "status": "open",
+                         "resolution": "none", "source": rule["origin"], "detail": str(err)})
+
+    def priority(rule):  # a number like any other: the double nearest to what was written
+        return dec(rule.get("priority", 0))
+
+    def applies(rule, scope):
+        return "when" not in rule or boolean(ev(rule["when"], scope))
+
+    def of_kind(kind):  # stable: equal priorities keep document order
+        return sorted((r for r in rules if r["kind"] == kind), key=lambda r: -priority(r))
+
+    def loses(previous_rule, rule, what):
+        """Same target, different value. True = this rule loses quietly; raises when it is a real conflict."""
+        if mf.get("conflictPolicy", "fail") == "fail" or priority(previous_rule) == priority(rule):
+            raise EvalError(f"conflicting {what} from {previous_rule['id']}")
+        return True
+
+    # Phase 1: compute
+    written = {}
+    for r in of_kind("compute"):
+        try:
+            if not applies(r, env):
+                continue
+            for a in r["assign"]:
+                if a.get("mode", "default") == "default" and lookup(pointer_path("data", a["field"]), env) is not None:
+                    continue
+                value = plain(ev(a["value"], env))
+                if a["field"] in written:
+                    if equal(written[a["field"]][0], value) or loses(written[a["field"]][1], r, a["field"]):
+                        continue
+                written[a["field"]] = (value, r)
+                set_pointer(data, a["field"], value)
+                effects.append({"type": "value", "field": a["field"], "value": value, "rule": r["id"]})
+        except EvalError as err:
+            engine_error(r, err)
+
+    # Phase 2: state
+    state = {}
+    for r in of_kind("state"):
+        try:
+            if not applies(r, env):
+                continue
+            # A rule applies all of its effects or, when one of them is a conflict, none of them:
+            # the outcome never depends on the order of the members of `set`.
+            staged = {}
+            for e in r["effects"]:
+                for prop, val in e["set"].items():
+                    key = (e["field"], prop)
+                    previous = staged.get(key) or state.get(key)
+                    if previous and (equal(previous[0], val) or loses(previous[1], r, f"{prop} of {e['field']}")):
+                        continue
+                    staged[key] = (val, r)
+            state.update(staged)
+        except EvalError as err:
+            engine_error(r, err)
+    grouped = {}
+    for (field, prop), (val, r) in state.items():
+        grouped.setdefault((field, r["id"]), {})[prop] = val
+    effects += [{"type": "state", "field": f, "set": s, "rule": rid} for (f, rid), s in grouped.items()]
+
+    # Phase 3: validation
+    for r in of_kind("validation"):
+        try:
+            target = r["target"]
+            if "type" in target:
+                # once per field bound to the type, in pointer order, with `value` and `field` in scope
+                pointers = sorted(p for p, t in field_types.items() if t == target["type"])
+                scopes = [(dict(env, value=lookup(pointer_path("data", p), env), field=p), [p]) for p in pointers]
+            elif "forEach" in r:
+                coll = lookup(pointer_path("data", r["forEach"]), env)
+                if coll is None:
+                    coll = []
+                if not isinstance(coll, list):
+                    raise EvalError(f"forEach {r['forEach']} is not a list")
+                own = [target["field"]] if "field" in target else target.get("fields", [])
+                scopes = [(dict(env, item=x), [f"{r['forEach']}/{i}{p}" for p in own]) for i, x in enumerate(coll)]
+            else:
+                scopes = [(env, [target["field"]] if "field" in target else list(target.get("fields", [])))]
+            for scope, fields in scopes:
+                if not applies(r, scope) or boolean(ev(r["assert"], scope)):
+                    continue
+                spec = r["finding"]
+                args = {k: plain(ev(x, scope)) for k, x in spec.get("args", {}).items()}
+                acceptance = r.get("acceptance", {})
+                severity = r["severity"]
+                status, resolution = "open", "none"
+                if severity == "error" and acceptance.get("allowed"):
+                    resolution = "accept-risk"
+                    given = resolutions.get((r["id"], "accept-risk"))
+                    role_ok = not acceptance.get("roles") or bool(roles & set(acceptance["roles"]))
+                    justified = acceptance.get("justification", "required") == "none" or bool(
+                        (given or {}).get("justification"))
+                    if given and role_ok and justified:
+                        status = "accepted"
+                elif severity == "warning" and r.get("acknowledgement") == "required":
+                    resolution = "acknowledge"
+                    if (r["id"], "acknowledge") in resolutions:
+                        status = "acknowledged"
+                finding = {
+                    "rule": r["id"], "code": spec["code"], "severity": severity,
+                    "message": fill(catalog.get(spec["message"], spec["message"]), args),
+                    "fields": fields,
+                    "blocking": status == "open" and (severity == "error" or resolution == "acknowledge"),
+                    "status": status, "resolution": resolution, "source": r["origin"],
+                }
+                location = {k: target[k] for k in VIEW_KEYS if k in target}
+                if location:
+                    finding["location"] = location
+                if acceptance.get("roles"):
+                    finding["acceptableBy"] = acceptance["roles"]
+                findings.append(finding)
+        except EvalError as err:
+            engine_error(r, err)
+
+    decision = "deny" if any(f["blocking"] for f in findings) else "allow"
+
+    # Phase 4: action - server only, and only when allowed. The host runs commands after it has persisted.
+    if decision == "allow" and not client:
+        for r in of_kind("action"):
+            try:
+                if not applies(r, env):
+                    continue
+                for c in r["commands"]:
+                    cmd = {"name": c["name"], "type": c["type"], "rule": r["id"],
+                           "idempotencyKey": ":".join(render(plain(ev(p, env))) for p in c["idempotencyKey"]),
+                           "payload": {k: plain(ev(x, env)) for k, x in c.get("payload", {}).items()}}
+                    if "ref" in c:
+                        cmd["ref"] = c["ref"]
+                    commands.append(cmd)
+            except EvalError as err:
+                engine_error(r, err)
+                decision, commands = "deny", []
+                break
+
+    return {"ruleset": mf["id"], "version": mf["version"], "checksum": mf["checksum"],
+            "decision": decision, "findings": findings, "effects": effects, "commands": commands}