sqllocks-shape-behavior 0.9.1__py3-none-any.whl

shape_behavior/__init__.py

@@ -0,0 +1,40 @@
+"""Shape plugin: behavior models (state machines on a virtual clock).
+
+The public names are importable from here, lazily: importing the package loads no module of
+this plugin beyond this file, and none of NumPy or Arrow. See ``docs/plugins/behavior.md``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+SHAPE_API = "1.0"
+
+_EXPORTS = {
+    "Module": "shape_behavior.model",
+    "ModuleError": "shape_behavior.model",
+    "load_module": "shape_behavior.model",
+    "Population": "shape_behavior.population",
+    "SimConfig": "shape_behavior.simulator",
+    "Simulator": "shape_behavior.simulator",
+    "Checkpoint": "shape_behavior.simulator",
+    "EVENT_SCHEMA": "shape_behavior.events",
+    "import_gmf": "shape_behavior.gmf",
+    "ImportResult": "shape_behavior.gmf",
+    "Unsupported": "shape_behavior.gmf",
+    "UnsupportedGmfError": "shape_behavior.gmf",
+    "register_state_type": "shape_behavior.extension",
+    "StateHandler": "shape_behavior.extension",
+    "StateContext": "shape_behavior.extension",
+    "Emission": "shape_behavior.extension",
+}
+
+__all__ = sorted(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'shape_behavior' has no attribute {name!r}")
+    return getattr(importlib.import_module(module), name)

shape_behavior/behaviors.py

@@ -0,0 +1,150 @@
+"""Behavior modules as ``shape.behaviors`` plugins (plugin API v1, ``Behavior`` protocol).
+
+A :class:`ModuleBehavior` wraps one :class:`~shape_behavior.model.Module` so the engine, the
+plugin host, ``shape plugins list`` and the conformance kit can all reach it by name::
+
+    from shape_behavior.behaviors import behavior
+
+    b = behavior({"format": "shape-behavior/1", "name": "my_process", "states": {...}})
+    events = b.simulate(population=1000, seed=7, years=3)   # a pyarrow.Table
+
+The built-in examples register under ``shape.behaviors`` through the classes at the bottom of
+this file; a third-party package registers its own module the same way
+(``docs/plugins/behavior.md``, section 10).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from shape_behavior.extension import get_handler
+from shape_behavior.model import EVENT_KINDS, Module, load_module
+
+SHAPE_API = "1.0"
+VERSION = "1.0"
+
+DEFAULT_POPULATION: dict[str, Any] = {
+    "age_at_start": {"kind": "uniform", "low": 0, "high": 90},
+    "attributes": {"gender": {"kind": "categorical", "values": {"F": 0.5, "M": 0.5}}},
+}
+
+
+def population_settings(modules: list[Module]) -> dict[str, Any]:
+    """The population settings the modules ask for (``population_defaults``; the first module
+    wins on a clash), or :data:`DEFAULT_POPULATION` when none asks."""
+    import copy
+
+    spec: dict[str, Any] = {}
+    for m in reversed(modules):
+        spec.update(m.doc.get("population_defaults", {}))
+    return spec or copy.deepcopy(DEFAULT_POPULATION)
+
+
+class ModuleBehavior:
+    """One module as a ``shape.behaviors`` plugin: name, version, states, attributes, events."""
+
+    def __init__(self, module: Module | dict[str, Any] | str, version: str = VERSION) -> None:
+        self.module = load_module(module)
+        self.name: str = self.module.name
+        self.version: str = str(self.module.doc.get("version", version))
+        self.states: list[str] = list(self.module.states)
+        self.attributes: list[str] = sorted(self.module.attribute_uses())
+        self.events: list[str] = _event_kinds(self.module)
+
+    def simulate(self, population: int, seed: int, years: float) -> Any:
+        """Events of ``population`` entities over ``years`` from 2020-01-01, deterministic per
+        ``seed`` (an Arrow table in :data:`shape_behavior.EVENT_SCHEMA`)."""
+        from shape_behavior.population import Population
+        from shape_behavior.simulator import SimConfig, Simulator
+        from shape_behavior.timeutil import add_years, to_us
+
+        start = "2020-01-01"
+        pop = Population.from_dict(population_settings([self.module]), size=population, start=start)
+        sim = Simulator([self.module], pop, SimConfig(seed=seed))
+        return sim.run_until(add_years(to_us(start), years))
+
+
+def behavior(module: Module | dict[str, Any] | str, version: str = VERSION) -> ModuleBehavior:
+    """A :class:`ModuleBehavior` for a module, a module document or a module file path."""
+    return ModuleBehavior(module, version)
+
+
+def _event_kinds(module: Module) -> list[str]:
+    kinds: set[str] = set()
+    for state in module.states.values():
+        kind = state["type"]
+        if kind == "event":
+            kinds.add(str(state["event"]))
+        elif kind in EVENT_KINDS:
+            kinds.add(EVENT_KINDS[kind])
+        else:  # a registered state type may declare the kinds it emits (optional `kinds`)
+            declared = getattr(get_handler(kind), "kinds", None)
+            if declared is not None:
+                kinds.update(declared(state))
+    return sorted(kinds)
+
+
+class Subscription(ModuleBehavior):
+    """Subscription lifecycle: free trial, conversion, monthly payments, pause and cancel."""
+
+    def __init__(self) -> None:
+        super().__init__("subscription")
+
+
+class EquipmentMaintenance(ModuleBehavior):
+    """Equipment maintenance: run, degrade, fail, repair, with scheduled inspections."""
+
+    def __init__(self) -> None:
+        super().__init__("equipment_maintenance")
+
+
+class HealthcareScreening(ModuleBehavior):
+    """A tiny healthcare example (screening, diagnosis, treatment), written from scratch."""
+
+    def __init__(self) -> None:
+        super().__init__("healthcare_screening")
+
+
+class EventSequence(ModuleBehavior):
+    """An ordered funnel of named events with a continue probability per step (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import event_sequence
+
+        super().__init__(event_sequence())
+
+
+class TelemetrySeries(ModuleBehavior):
+    """A regular reading per device with drift, noise, skipped and stuck readings (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import telemetry_series
+
+        super().__init__(telemetry_series())
+
+
+class TransactionStream(ModuleBehavior):
+    """Transactions as a Poisson process per entity, with refunds and reversals (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import transaction_stream
+
+        super().__init__(transaction_stream())
+
+
+class FileArrival(ModuleBehavior):
+    """A feed with an expected arrival per schedule slot: on time, late, missing, duplicated."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import file_arrival
+
+        super().__init__(file_arrival())
+
+
+class EntityLifecycle(ModuleBehavior):
+    """Create, update and delete events per entity (change-data-capture style)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import entity_lifecycle
+
+        super().__init__(entity_lifecycle())

shape_behavior/cli.py

@@ -0,0 +1,240 @@
+"""``shape behave``: run, check and import behavior modules.
+
+Reference: ``docs/plugins/behavior.md``, section 7.
+
+::
+
+    shape behave run subscription --population 10000 --years 3 --seed 7 -o out/
+    shape behave check my_module.json
+    shape behave import-gmf downloaded_module.json -o converted.json
+    shape behave examples -o modules/
+
+Nothing heavy loads at import time: NumPy, Arrow and the simulator load when a command runs.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from shape_behavior.params import (
+    PRIMITIVE_NAMES,
+    PrimitiveParamsError,
+    read_params,
+    unknown_primitive,
+)
+
+SHAPE_API = "1.0"
+
+
+class BehaveCommand:
+    """``shape behave COMMAND ...``."""
+
+    name = "behave"
+    help = "run state-machine behavior modules on a virtual clock (events as Parquet)"
+
+    def configure(self, parser: Any) -> None:
+        sub = parser.add_subparsers(dest="behave_cmd", required=True, metavar="COMMAND")
+        run = sub.add_parser("run", help="simulate a population and write the event stream")
+        run.add_argument(
+            "modules",
+            nargs="+",
+            metavar="MODULES",
+            help="module files (native or GMF JSON) or example names",
+        )
+        run.add_argument(
+            "--population", type=int, required=True, metavar="N", help="number of entities"
+        )
+        run.add_argument(
+            "--years", type=float, required=True, metavar="Y", help="years to simulate"
+        )
+        run.add_argument("--seed", type=int, default=0, help="random seed (default 0)")
+        run.add_argument("-o", "--out", required=True, metavar="OUT", help="output directory")
+        run.add_argument(
+            "--start", default="2020-01-01", help="virtual clock start (default 2020-01-01)"
+        )
+        run.add_argument(
+            "--population-spec",
+            metavar="FILE",
+            help="JSON population settings (attributes, age_at_start, arrival, lifetime)",
+        )
+        run.add_argument(
+            "--window-years", type=float, default=1.0, help="years per output file (default 1)"
+        )
+        run.add_argument(
+            "--poll", default="7 days", help="guard polling interval (default '7 days')"
+        )
+        run.add_argument("--strict", action="store_true", help="fail on unsupported GMF elements")
+        run.add_argument(
+            "--params",
+            metavar="FILE.json",
+            help="parameters of a primitive named in MODULES "
+            '({"format": "shape-behavior-params", "version": 1, "primitive": NAME, "params": {}})',
+        )
+        run.set_defaults(fn=_run)
+        check = sub.add_parser("check", help="validate modules; exit 1 when one is invalid")
+        check.add_argument("modules", nargs="+", metavar="MODULES")
+        check.add_argument("--strict", action="store_true", help="fail on unsupported GMF elements")
+        check.set_defaults(fn=_check)
+        imp = sub.add_parser(
+            "import-gmf", help="convert a GMF module and report what is unsupported"
+        )
+        imp.add_argument("file", help="the GMF JSON file you downloaded")
+        imp.add_argument("-o", "--out", metavar="OUT.json", help="write the native module here")
+        imp.add_argument("--strict", action="store_true", help="fail on unsupported elements")
+        imp.set_defaults(fn=_import)
+        ex = sub.add_parser("examples", help="list the built-in example modules, or write them")
+        ex.add_argument("-o", "--out", metavar="DIR", help="write the examples into DIR")
+        ex.set_defaults(fn=_examples)
+
+    def run(self, args: Any) -> int:
+        try:
+            return int(args.fn(args))
+        except (FileNotFoundError, json.JSONDecodeError, PrimitiveParamsError) as exc:
+            print(f"shape behave: {exc}", file=sys.stderr)
+            return 2
+        except ValueError as exc:  # includes ModuleError, UnsupportedGmfError
+            print(f"shape behave: {exc}", file=sys.stderr)
+            return 1
+
+
+def _load(sources: list[str], strict: bool, params: str | None = None) -> list[Any]:
+    from shape_behavior.model import load_module
+
+    primitive, values = read_params(Path(params)) if params else ("", {})
+    if params and primitive not in sources:
+        if primitive not in PRIMITIVE_NAMES:
+            raise unknown_primitive(primitive)
+        raise PrimitiveParamsError(
+            f"--params is for primitive {primitive!r}, which is not among the modules to run "
+            f"({', '.join(sources)})",
+            "primitive",
+        )
+    if params:
+        from shape_behavior.primitives import build
+    modules = []
+    for src in sources:
+        module = (
+            build(primitive, values)
+            if params and src == primitive
+            else load_module(src, strict=strict)
+        )
+        report = module.import_report
+        if report is not None and (report.unsupported or report.warnings):
+            print(f"{src}:\n{report.report()}", file=sys.stderr)
+        modules.append(module)
+    return modules
+
+
+def _run(args: Any) -> int:
+    import pyarrow.parquet as pq  # type: ignore[import-untyped]
+
+    from shape_behavior.behaviors import population_settings
+    from shape_behavior.population import Population
+    from shape_behavior.simulator import SimConfig, Simulator
+    from shape_behavior.timeutil import add_years, to_us
+
+    if args.population < 0 or args.years <= 0 or args.window_years <= 0:
+        print(
+            "shape behave: --population must be >= 0 and --years and --window-years > 0",
+            file=sys.stderr,
+        )
+        return 2
+    modules = _load(args.modules, args.strict, args.params)
+    if args.population_spec:
+        spec = json.loads(Path(args.population_spec).read_text(encoding="utf-8"))
+    else:
+        spec = population_settings(modules)
+    population = Population.from_dict(spec, size=args.population, start=args.start)
+    sim = Simulator(modules, population, SimConfig(seed=args.seed, poll=args.poll))
+    out = Path(args.out)
+    (out / "events").mkdir(parents=True, exist_ok=True)
+    start = to_us(args.start)
+    end = add_years(start, args.years)
+    started = time.perf_counter()
+    windows: list[dict[str, Any]] = []
+    cursor, part = start, 0
+    while cursor < end:
+        nxt = min(add_years(start, args.window_years * (part + 1)), end)
+        events = sim.run_until(nxt)
+        pq.write_table(events, out / "events" / f"part-{part:04d}.parquet", compression="snappy")
+        windows.append(
+            {
+                "file": f"events/part-{part:04d}.parquet",
+                "until": str(sim.now),
+                "rows": events.num_rows,
+            }
+        )
+        cursor, part = nxt, part + 1
+    pq.write_table(sim.entities(), out / "entities.parquet", compression="snappy")
+    elapsed = time.perf_counter() - started
+    total = sum(w["rows"] for w in windows)
+    manifest = {
+        "seed": args.seed,
+        "years": args.years,
+        "start": args.start,
+        "population": population.to_dict(),
+        "modules": [_module_entry(m, s) for m, s in zip(modules, args.modules, strict=True)],
+        "events": total,
+        "windows": windows,
+        "seconds": round(elapsed, 3),
+        "unsupported": [
+            str(u) for m in modules if m.import_report for u in m.import_report.unsupported
+        ],
+    }
+    (out / "run.json").write_text(
+        json.dumps(manifest, indent=2) + "\n", encoding="utf-8", newline="\n"
+    )
+    print(f"{total:,} events for {args.population:,} entities in {elapsed:.1f}s -> {out}")
+    return 0
+
+
+def _module_entry(module: Any, source: str) -> dict[str, Any]:
+    entry: dict[str, Any] = {"name": module.name, "digest": module.digest(), "source": source}
+    if "primitive" in module.doc:  # a primitive: record the parameters it ran with
+        entry["primitive"] = module.doc["primitive"]
+        entry["parameters"] = module.doc["parameters"]
+    return entry
+
+
+def _check(args: Any) -> int:
+    modules = _load(args.modules, args.strict)
+    for m in modules:
+        print(f"ok  {m.name}  ({len(m.states)} states)")
+    return 0
+
+
+def _import(args: Any) -> int:
+    from shape_behavior.gmf import import_gmf
+
+    result = import_gmf(Path(args.file), strict=args.strict)
+    print(result.report())
+    if args.out:
+        Path(args.out).write_text(
+            json.dumps(result.module.to_dict(), indent=2) + "\n", encoding="utf-8", newline="\n"
+        )
+        print(f"wrote {args.out}")
+    return 0
+
+
+def _examples(args: Any) -> int:
+    import importlib.resources
+
+    from shape_behavior.model import examples
+
+    names = examples()
+    if not args.out:
+        print("\n".join(names))
+        return 0
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        text = (
+            importlib.resources.files("shape_behavior") / "examples" / f"{name}.json"
+        ).read_text(encoding="utf-8")
+        (out / f"{name}.json").write_text(text, encoding="utf-8", newline="\n")
+    print(f"wrote {len(names)} modules to {out}")
+    return 0

shape_behavior/conditions.py

@@ -0,0 +1,221 @@
+"""Conditions: validation, and compilation into vectorized tests over rows of entities."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from shape_behavior.timeutil import to_us, unit_us
+
+OPS = ("==", "!=", "<", "<=", ">", ">=")
+NIL_OPS = ("is_nil", "is_not_nil")
+LEAF_TYPES = ("true", "false", "attribute", "age", "date", "active_condition", "active_medication")
+GROUP_TYPES = ("and", "or", "at_least", "at_most")
+_CMP: dict[str, Callable[[Any, Any], Any]] = {
+    "==": np.equal,
+    "!=": np.not_equal,
+    "<": np.less,
+    "<=": np.less_equal,
+    ">": np.greater,
+    ">=": np.greater_equal,
+}
+_Test = Callable[[Any, Any, Any], Any]
+
+
+def _num(v: Any) -> float | None:
+    if isinstance(v, bool):
+        return 1.0 if v else 0.0
+    if isinstance(v, (int, float)):
+        return float(v)
+    return None
+
+
+def check(doc: Any, where: str) -> list[str]:
+    """Problems with a condition document, empty when it is fine."""
+    if not isinstance(doc, dict):
+        return [f"{where}: a condition must be an object"]
+    kind = doc.get("type")
+    if kind in ("true", "false"):
+        return []
+    if kind == "attribute":
+        out = [] if isinstance(doc.get("attribute"), str) else [f"{where}: needs 'attribute'"]
+        op = doc.get("op")
+        if op in NIL_OPS:
+            return out
+        if op not in OPS:
+            return [*out, f"{where}: op must be one of {', '.join(OPS + NIL_OPS)}"]
+        if "value" not in doc:
+            out.append(f"{where}: needs 'value'")
+        elif isinstance(doc["value"], str) and op not in ("==", "!="):
+            out.append(f"{where}: text attributes only compare with == and !=")
+        elif _num(doc["value"]) is None and not isinstance(doc["value"], str):
+            out.append(f"{where}: value must be a number, a bool or text")
+        return out
+    if kind in ("age", "date"):
+        out = []
+        if doc.get("op") not in OPS:
+            out.append(f"{where}: op must be one of {', '.join(OPS)}")
+        if "value" not in doc:
+            return [*out, f"{where}: needs 'value'"]
+        try:
+            if kind == "age":
+                if _num(doc["value"]) is None:
+                    raise ValueError("age value must be a number")
+                unit_us(doc.get("unit", "years"))
+            else:
+                to_us(doc["value"])
+        except (ValueError, TypeError) as exc:
+            out.append(f"{where}: {exc}")
+        return out
+    if kind in ("active_condition", "active_medication"):
+        codes = doc.get("codes")
+        if not isinstance(codes, list) or not codes or not all(code_of(c) for c in codes):
+            return [f"{where}: needs a non-empty list of 'codes'"]
+        return []
+    if kind in GROUP_TYPES:
+        subs = doc.get("conditions")
+        if not isinstance(subs, list) or not subs:
+            return [f"{where}: needs a non-empty list of 'conditions'"]
+        out = []
+        if kind in ("at_least", "at_most"):
+            key = "minimum" if kind == "at_least" else "maximum"
+            if isinstance(doc.get(key), bool) or not isinstance(doc.get(key), int):
+                out.append(f"{where}: needs an integer {key!r}")
+        for i, sub in enumerate(subs):
+            out += check(sub, f"{where}.conditions[{i}]")
+        return out
+    if kind == "not":
+        return check(doc.get("condition"), f"{where}.condition")
+    return [f"{where}: unknown condition type {kind!r}"]
+
+
+def code_of(c: Any) -> str | None:
+    """The code string of a ``codes`` entry (a dict with ``code``, or the string itself)."""
+    if isinstance(c, str) and c:
+        return c
+    if isinstance(c, dict) and isinstance(c.get("code"), str) and c["code"]:
+        return str(c["code"])
+    return None
+
+
+def walk(doc: Any) -> list[dict[str, Any]]:
+    """Every condition node in ``doc``, the root first."""
+    out = [doc]
+    if doc.get("type") in GROUP_TYPES:
+        for sub in doc["conditions"]:
+            out += walk(sub)
+    elif doc.get("type") == "not":
+        out += walk(doc["condition"])
+    return out
+
+
+class Compiled:
+    """A compiled condition: ``test(store, rows, time)`` gives a bool array over the rows;
+    ``ready`` (``None`` unless the condition depends only on age) gives the earliest time at
+    which it holds, ``INF`` for never."""
+
+    def __init__(self, test: _Test, ready: Callable[[Any, Any], Any] | None = None) -> None:
+        self.test = test
+        self.ready = ready
+
+
+def compile_condition(doc: dict[str, Any], bit: Callable[[str, str], int]) -> Compiled:
+    """Compile ``doc``; ``bit(kind, code)`` gives the bit of a code in the ``condition`` or
+    ``medication`` active set."""
+    kind = doc["type"]
+    if kind == "true":
+        return Compiled(lambda s, r, t: np.ones(len(r), bool))
+    if kind == "false":
+        return Compiled(lambda s, r, t: np.zeros(len(r), bool))
+    if kind == "attribute":
+        return Compiled(_attribute_test(doc))
+    if kind == "age":
+        return _age(doc)
+    if kind == "date":
+        value = to_us(doc["value"])
+        cmp = _CMP[doc["op"]]
+        return Compiled(lambda s, r, t: cmp(t, value))
+    if kind in ("active_condition", "active_medication"):
+        mask = 0
+        which = "condition" if kind == "active_condition" else "medication"
+        for c in doc["codes"]:
+            mask |= 1 << bit(which, str(code_of(c)))
+        field = "cond_mask" if which == "condition" else "med_mask"
+        m = np.uint64(mask)
+        return Compiled(lambda s, r, t: (getattr(s, field)[r] & m) != 0)
+    if kind == "not":
+        inner = compile_condition(doc["condition"], bit).test
+        return Compiled(lambda s, r, t: ~inner(s, r, t))
+    subs = [compile_condition(c, bit) for c in doc["conditions"]]
+    tests = [c.test for c in subs]
+    if kind == "and":
+        ready = _and_ready(subs)
+        return Compiled(lambda s, r, t: np.logical_and.reduce([f(s, r, t) for f in tests]), ready)
+    if kind == "or":
+        return Compiled(lambda s, r, t: np.logical_or.reduce([f(s, r, t) for f in tests]))
+    count = doc.get("minimum" if kind == "at_least" else "maximum", 0)
+
+    def counted(s: Any, r: Any, t: Any) -> Any:
+        n = np.sum([f(s, r, t) for f in tests], axis=0)
+        return n >= count if kind == "at_least" else n <= count
+
+    return Compiled(counted)
+
+
+def _and_ready(subs: list[Compiled]) -> Callable[[Any, Any], Any] | None:
+    readies = [c.ready for c in subs]
+    if any(r is None for r in readies):
+        return None
+    fns: list[Callable[[Any, Any], Any]] = [r for r in readies if r is not None]
+    return lambda s, r: np.maximum.reduce([f(s, r) for f in fns])
+
+
+def _attribute_test(doc: dict[str, Any]) -> _Test:
+    name, op = doc["attribute"], doc["op"]
+    if op == "is_nil":
+        return lambda s, r, t: s.is_nil(name, r)
+    if op == "is_not_nil":
+        return lambda s, r, t: ~s.is_nil(name, r)
+    value = doc["value"]
+    cmp = _CMP[op]
+    if isinstance(value, str):
+
+        def text_test(s: Any, r: Any, t: Any) -> Any:
+            if name in s.num:  # a numeric attribute never equals text
+                return np.full(len(r), op == "!=")
+            code = s.vindex.get(name, {}).get(value, -2)
+            return cmp(s.cat[name][r], code) if name in s.cat else np.full(len(r), op == "!=")
+
+        return text_test
+    num = float(_num(value) or 0.0)
+
+    def num_test(s: Any, r: Any, t: Any) -> Any:
+        if name not in s.num:
+            return np.zeros(len(r), bool)
+        x = s.num[name][r]
+        res = cmp(x, num)
+        return res | np.isnan(x) if op == "!=" else res
+
+    return num_test
+
+
+def _age(doc: dict[str, Any]) -> Compiled:
+    threshold = round(float(doc["value"]) * unit_us(doc.get("unit", "years")))
+    op = doc["op"]
+    cmp = _CMP[op]
+
+    def test(s: Any, r: Any, t: Any) -> Any:
+        return cmp(t - s.born[r], threshold)
+
+    ready: Callable[[Any, Any], Any] | None = None
+    if op in (">=", ">"):
+        # the first microsecond at which age >= value (or > value)
+        def ready(s: Any, r: Any) -> Any:
+            return s.born[r] + threshold + (1 if op == ">" else 0)
+
+    elif op in ("<", "<="):
+        # holds from the start and stops: handled by the caller as "now or never"
+        ready = None
+    return Compiled(test, ready)