gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/domain/paging_sim.py

@@ -0,0 +1,141 @@
+"""Page-replacement simulator — the real algorithms (FIFO / LRU / Optimal) run over a reference
+string with a bounded frame budget. Deterministic and exact, so it is ground truth for the thrashing
+game and a substrate for other paging games (policy comparison, Belady's anomaly, next-eviction).
+
+This is a faithful implementation of the algorithms, not a hand-waved model — but it is NOT xv6-live
+(xv6 has no eviction). A live page-replacement mechanism in the kernel is a separate, larger build.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ReplayResult:
+    policy: str
+    frames: int
+    faults: int
+    evictions: int
+    fault_at: list          # bool per reference — was it a page fault?
+
+
+def simulate(refs, frames: int, policy: str = "lru") -> ReplayResult:
+    """Run `policy` over `refs` with `frames` physical frames. FIFO / LRU / OPT."""
+    refs = list(refs)
+    policy = policy.lower()
+    if frames <= 0:
+        return ReplayResult(policy, frames, len(refs), 0, [True] * len(refs))
+    if policy == "opt":
+        return _opt(refs, frames)
+    inset: set = set()
+    order: list = []        # FIFO: insertion order; LRU: recency (least-recent at front)
+    faults = evictions = 0
+    fault_at: list = []
+    for pg in refs:
+        hit = pg in inset
+        fault_at.append(not hit)
+        if hit:
+            if policy == "lru":
+                order.remove(pg); order.append(pg)      # touch -> most recent
+            continue
+        faults += 1
+        if len(inset) >= frames:
+            victim = order.pop(0)                        # FIFO oldest / LRU least-recent
+            inset.discard(victim); evictions += 1
+        inset.add(pg); order.append(pg)
+    return ReplayResult(policy, frames, faults, evictions, fault_at)
+
+
+def _opt(refs, frames) -> ReplayResult:
+    inset: set = set()
+    faults = evictions = 0
+    fault_at: list = []
+    for i, pg in enumerate(refs):
+        hit = pg in inset
+        fault_at.append(not hit)
+        if hit:
+            continue
+        faults += 1
+        if len(inset) >= frames:
+            def next_use(p):
+                for j in range(i + 1, len(refs)):
+                    if refs[j] == p:
+                        return j
+                return 1 << 30                            # never used again -> evict first
+            victim = max(inset, key=next_use)
+            inset.discard(victim); evictions += 1
+        inset.add(pg)
+    return ReplayResult("opt", frames, faults, evictions, fault_at)
+
+
+def resident_state(refs, frames: int, policy: str = "lru") -> tuple:
+    """Replay `refs` and return (resident_set, order) at the end. `order` is eviction order: FIFO
+    insertion order / LRU least-recent-first — so order[0] is the next victim when full."""
+    policy = policy.lower()
+    inset: set = set()
+    order: list = []
+    for pg in refs:
+        if pg in inset:
+            if policy == "lru":
+                order.remove(pg); order.append(pg)
+            continue
+        if len(inset) >= frames and order:
+            victim = order.pop(0)
+            inset.discard(victim)
+        inset.add(pg); order.append(pg)
+    return inset, order
+
+
+# -- metrics (the observable signature) -------------------------------------------------------- #
+def fault_rate(res: ReplayResult) -> float:
+    return res.faults / len(res.fault_at) if res.fault_at else 0.0
+
+
+def unique_pages(refs) -> int:
+    return len(set(refs))
+
+
+def peak_working_set(refs, window: int = 10) -> int:
+    """Largest number of distinct pages touched within any `window`-reference sliding window."""
+    from collections import deque
+    w: deque = deque()
+    seen: dict = {}
+    peak = 0
+    for p in refs:
+        w.append(p); seen[p] = seen.get(p, 0) + 1
+        if len(w) > window:
+            old = w.popleft(); seen[old] -= 1
+            if seen[old] == 0:
+                del seen[old]
+        peak = max(peak, len(seen))
+    return peak
+
+
+def ws_growth(refs) -> float:
+    """How much the distinct-page set grows from the first half to the second (phase change)."""
+    if len(refs) < 4:
+        return 0.0
+    h = len(refs) // 2
+    a = len(set(refs[:h])); b = len(set(refs[h:]))
+    return max(0.0, (b - a) / max(a, 1))
+
+
+def locality(refs, window: int = 8) -> float:
+    """Fraction of reuses whose previous touch was within `window` references (1 = tight locality)."""
+    last: dict = {}
+    hits = total = 0
+    for i, p in enumerate(refs):
+        if p in last:
+            total += 1
+            if i - last[p] <= window:
+                hits += 1
+        last[p] = i
+    return hits / total if total else 0.0
+
+
+def run_features(refs, frames: int, policy: str = "lru") -> dict:
+    """The observable signature of a run — what the thrashing game shows the student."""
+    res = simulate(refs, frames, policy)
+    return {"fault_rate": fault_rate(res), "frames": frames,
+            "working_set": peak_working_set(refs), "unique_pages": unique_pages(refs),
+            "ws_growth": ws_growth(refs), "locality": locality(refs)}

gini/domain/pricing.py

@@ -0,0 +1,199 @@
+"""GINI $ — the toy cloud-economics model behind the dashboard.
+
+Every element you place is a "rented" cloud resource billed by the hour in GINI $ (a
+pretend currency — purely pedagogical, so students feel pay-as-you-go without spending
+real money). The dashboard accrues `rate_per_hr × elapsed` while a lab runs.
+
+Rates are deliberately round numbers that *teach the relative cost of cloud building
+blocks*: a managed database costs more than a plain VM, which costs more than a switch.
+Override any rate in Settings → Pricing (persisted to ~/.gini).
+"""
+from __future__ import annotations
+
+# Default rental rates in GINI $ per hour, keyed by element type_key.
+DEFAULT_RATES: dict[str, float] = {
+    # --- compute (you pay most for managed/large compute) ------------------- #
+    "instance": 10.0,        # VM
+    "kinstance": 14.0,       # Kata Instance — a real microVM, so it costs more than a VM image
+    "container": 5.0,
+    "host": 2.0,             # a plain Machine / end host
+    "desktop": 3.0,          # a headful Machine (lean host + a light X desktop over noVNC)
+    "xv6": 2.0,              # xv6 teaching kernel under QEMU-RISC-V (a single-CPU learning VM)
+    # --- OS Zoo (emulated historical OSes; each is a QEMU/emulator VM) --------- #
+    "freedos": 2.0,
+    "kolibri": 2.0,
+    "menuet": 2.0,
+    "msdos": 2.0,          # MS-DOS 6.22 preset (QEMU; disk image downloaded)
+    "mac7": 3.0,            # Mac System 7 preset (Basilisk II; image/ROM downloaded)
+    "win31": 3.0,          # Windows 3.11 preset (DOSBox; image downloaded)
+    "oszoo_byo": 3.0,        # bring-your-own classic OS (Windows/Mac) under emulation
+    # --- serverless (cheap, scale-to-zero; pay per use, not per idle hour) --- #
+    "function": 1.0,         # a handler in the shared FaaS runtime
+    "api_gateway": 5.0,      # a managed API front door (Traefik)
+    # --- containers & kubernetes -------------------------------------------- #
+    "pod": 5.0,              # a Deployment — billed per replica (scaling costs money)
+    "k8s_cluster": 8.0,      # a managed control plane (k3s)
+    "k8s_node": 8.0,         # a worker node (a VM)
+    "instance_group": 2.0,   # Pod Autoscaler (HPA) — the autoscaling feature itself
+    "registry": 3.0,         # an image registry
+    # --- networking --------------------------------------------------------- #
+    "router": 3.0,
+    "ovs": 3.0,              # OpenFlow switch (a gRouter in OF mode)
+    "controller": 4.0,       # SDN controller
+    "firewall": 2.0,
+    "vnf": 3.0,              # a network-function container in the path (NFV)
+    "switch": 1.0,
+    "wap": 1.5,              # access point
+    "hub": 0.5,
+    "cloud": 1.0,            # the Internet element = a NAT gateway (small fee)
+    # --- managed services (the expensive, "someone runs it for you" tier) --- #
+    "database": 12.0,
+    "nosql": 10.0,
+    "object_store": 8.0,
+    "stream": 9.0,
+    "queue": 6.0,
+    "messaging": 6.0,
+    "cache": 4.0,
+    "load_balancer": 5.0,
+    "proxy": 3.0,
+    "web_app": 4.0,
+    # --- observability / workload ------------------------------------------ #
+    "metrics": 5.0,          # Prometheus
+    "dashboard": 5.0,        # Grafana
+    "tracing": 5.0,          # Jaeger
+    "load_generator": 2.0,
+}
+
+# Instance "size" tiers (like cloud instance types). level -> (label, vCPUs, mem_MB,
+# cost_multiplier). Cost roughly doubles each step up, mirroring real cloud pricing.
+SIZE_TIERS: dict[int, tuple[str, float, int, int]] = {
+    1: ("S",  0.5,  256, 1),
+    2: ("M",  1.0,  512, 2),
+    3: ("L",  2.0, 1024, 4),
+    4: ("XL", 4.0, 2048, 8),
+}
+SIZE_MIN, SIZE_MAX = 1, 4
+
+
+def size_level(level) -> int:
+    try:
+        return max(SIZE_MIN, min(SIZE_MAX, int(level or 1)))
+    except (TypeError, ValueError):
+        return 1
+
+
+def size_tier(level) -> tuple[str, float, int, int]:
+    return SIZE_TIERS[size_level(level)]
+
+
+def size_label(level) -> str:
+    return size_tier(level)[0]
+
+
+def size_cost_mult(level) -> int:
+    return size_tier(level)[3]
+
+
+def resizable(type_key: str) -> bool:
+    """Which elements expose a size knob — things that run a real workload container
+    and meaningfully have a capacity (compute + managed services). Not switches/hubs."""
+    from ..services.cloud_catalog import is_service   # lazy: keep domain below services
+    return is_service(type_key) or type_key in ("instance", "kinstance", "container", "host", "xv6")
+
+
+# Dashboard breakdown groups. Order is the display order.
+CATEGORIES: dict[str, tuple[str, ...]] = {
+    "Compute": ("instance", "kinstance", "container", "host", "desktop", "xv6"),
+    "Serverless": ("function", "api_gateway"),
+    "Kubernetes": ("k8s_cluster", "pod", "k8s_node", "instance_group", "registry"),
+    "Networking": ("router", "ovs", "controller", "firewall", "vnf", "switch",
+                   "wap", "hub", "cloud"),
+    "Services": ("database", "nosql", "object_store", "stream", "queue",
+                 "messaging", "cache", "load_balancer", "proxy", "web_app"),
+    "Observability": ("metrics", "dashboard", "tracing", "load_generator"),
+    "OS Zoo": ("freedos", "kolibri", "menuet", "msdos", "mac7", "win31", "oszoo_byo"),
+}
+CATEGORY_ORDER = tuple(CATEGORIES.keys())
+_CAT_OF = {tk: cat for cat, tks in CATEGORIES.items() for tk in tks}
+
+# the type_keys that are actually billable (everything in a category).
+BILLABLE = frozenset(_CAT_OF)
+
+# Intentionally-free elements, listed so the coverage test can tell "deliberately not
+# billed" from "someone added an element and forgot to price it" (the latter would make
+# the meter under-count — the bug this guards against). Two kinds:
+#   * grouping boundaries — visual regions, not rented resources;
+#   * placeholders — elements with no real runtime yet (priced once they become real).
+FREE = frozenset({
+    "vpc", "cloud_subnet", "region",              # grouping boundaries
+    "security_group", "gateway", "block_volume",  # not-yet-real placeholders
+    "terminal", "storage_volume",                 # xv6 peripherals (software devices, no cost)
+    # A GINI32 board is REAL hardware the student already owns, not a rented
+    # resource. The meter models a cloud bill, so billing your own $5 chip would be
+    # the wrong lesson — the relay that carries it is part of the lab, not a rental.
+    "gini32",
+    # Sources / Sinks (riders) — instruments that run inside a donor, no container of their own
+    "ping_probe", "http_probe", "packet_view", "dns_probe", "traceroute_probe",
+    "iperf_client", "iperf_server", "iface_stats", "xv6_shell", "xv6_workload",
+})
+
+
+def category_of(type_key: str) -> str | None:
+    return _CAT_OF.get(type_key)
+
+
+def rate_of(type_key: str, overrides: dict | None = None) -> float:
+    """GINI $/hr for a type, honoring user overrides from Settings → Pricing."""
+    if overrides and type_key in overrides:
+        try:
+            return max(0.0, float(overrides[type_key]))
+        except (TypeError, ValueError):
+            pass
+    return float(DEFAULT_RATES.get(type_key, 0.0))
+
+
+def _int(v, default: int = 1) -> int:
+    try:
+        return int(float(v))
+    except (TypeError, ValueError):
+        return default
+
+
+def units(type_key: str, properties: dict | None) -> int:
+    """How many billable units one element represents. A Pod is a Deployment of N
+    replicas, so it bills per replica — scaling a workload up costs more, which is the
+    whole point of Kubernetes/HPA. Everything else is a single unit."""
+    if type_key == "pod":
+        return max(1, _int((properties or {}).get("Replicas"), 1))
+    return 1
+
+
+def bill(topology, overrides: dict | None = None) -> dict:
+    """Cost estimate for the whole canvas.
+
+    Returns::
+
+        {"rate_per_hr": float,           # GINI $/hr for every billable element
+         "count": int,                   # number of billable elements
+         "by_category": {cat: {"rate": float, "count": int}}}   # display order
+    """
+    by_cat: dict[str, dict] = {c: {"rate": 0.0, "count": 0} for c in CATEGORY_ORDER}
+    total = 0.0
+    n = 0
+    for d in getattr(topology, "devices", {}).values():
+        tk = getattr(d, "type_key", None)
+        if tk not in BILLABLE:
+            continue
+        cat = _CAT_OF[tk]
+        # bigger instance size = proportionally more GINI $/hr (x1/x2/x4/x8)
+        mult = size_cost_mult(getattr(d, "size", 1)) if resizable(tk) else 1
+        # a Pod bills per replica (scaling a workload costs more)
+        qty = units(tk, getattr(d, "properties", None))
+        r = rate_of(tk, overrides) * mult * qty
+        by_cat[cat]["rate"] += r
+        by_cat[cat]["count"] += 1
+        total += r
+        n += 1
+    # drop empty categories so the strip stays compact
+    by_cat = {c: v for c, v in by_cat.items() if v["count"]}
+    return {"rate_per_hr": round(total, 2), "count": n, "by_category": by_cat}

gini/domain/probes.py

@@ -0,0 +1,226 @@
+"""Behavioral probes — the language of GINI-as-oracle win conditions.
+
+A behavioral objective asserts a fact about the RUNNING system, which only GINI's runtime can
+witness. This module parses the probe strings and evaluates them against a `Runner` — the thin
+seam over the running topology (Docker exec of ping/curl, flow-table reads). GINI, never the
+model, produces the verdict.
+
+Probe grammar (Phase 2):
+    reach(A -> B) == ok|fail          # L3 reachability (ICMP); with :port → TCP/L4
+    reach(A -> B:port) == ok|fail
+    reach(A -> B, all) == ok          # EVERY A-B pair, not just some (see TypeRunner.reach_all)
+    ping(A -> B) == ok|fail           # explicit ICMP
+    http(A -> B:port) == ok|fail      # an HTTP 2xx from A to B:port
+    balances(LB, >= n)                # LB fans out to at least n live backends
+    flow_installed(OVS, <match>)      # an OpenFlow rule matching <match> is installed
+
+Pure parsing + evaluation; the real Docker-backed runner lives in `services/probe_runner.py`,
+and a `FakeRunner` (facts dict) makes everything unit-testable offline.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Protocol
+
+# probe kinds
+REACH, PING, HTTP, BALANCES, FLOW = "reach", "ping", "http", "balances", "flow_installed"
+MEASURE = "measure"
+
+_REACH_RE = re.compile(                          # `\w+` or a slot-scoped `\w+@\w+` (e.g. host@A)
+    r"^\s*(reach|ping|http)\(\s*([\w@]+)\s*->\s*([\w@]+)(?::(\d+))?\s*(?:,\s*(all|any)\s*)?\)"
+    r"\s*==\s*(ok|fail)\s*$")
+_BAL_RE = re.compile(r"^\s*balances\(\s*(\w+)\s*,\s*>=\s*(\d+)\s*\)\s*$")
+_FLOW_RE = re.compile(r"^\s*flow_installed\(\s*(\w+)\s*,\s*(.+?)\s*\)\s*$")
+# measure(<rider_type>, <metric>) <op> <value> — an output assertion on a Sink/Source measurement
+_MEASURE_RE = re.compile(
+    r"^\s*measure\(\s*(\w+)\s*,\s*(\w+)\s*\)\s*(>=|<=|==|!=|>|<)\s*(-?\d+(?:\.\d+)?)\s*$")
+
+
+class ProbeError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Probe:
+    kind: str
+    src: str = ""
+    dst: str = ""
+    port: int | None = None
+    expect_ok: bool = True      # for reach/ping/http: True = expect success, False = expect failure
+    n: int = 0                  # for balances
+    match: str = ""             # for flow_installed
+    quant: str = "any"          # "any" = SOME pair satisfies it; "all" = EVERY pair must
+    metric: str = ""            # for measure: the rider metric (loss_pct, packets, mbps, …)
+    op: str = ">="              # for measure: comparison operator
+    value: float = 0.0          # for measure: the threshold
+
+
+class Runner(Protocol):
+    """The running-topology seam. `available()` is False when there's no live runtime, so
+    behavioral objectives stay `pending` rather than being wrongly failed."""
+    def available(self) -> bool: ...
+    def reach(self, src: str, dst: str, port: int | None = None) -> bool: ...
+    def http(self, src: str, dst: str, port: int) -> bool: ...
+    def backends(self, lb: str) -> int: ...
+    def flow(self, ovs: str, match: str) -> bool: ...
+    def measure(self, rider_type: str, metric: str) -> float | None: ...
+
+
+def parse(probe: str) -> Probe:
+    m = _REACH_RE.match(probe or "")
+    if m:
+        kind, src, dst, port, quant, expect = m.groups()
+        return Probe(kind=kind, src=src, dst=dst,
+                     port=int(port) if port else None, expect_ok=(expect == "ok"),
+                     quant=quant or "any")
+    m = _BAL_RE.match(probe or "")
+    if m:
+        return Probe(kind=BALANCES, src=m.group(1), n=int(m.group(2)))
+    m = _FLOW_RE.match(probe or "")
+    if m:
+        return Probe(kind=FLOW, src=m.group(1), match=m.group(2))
+    m = _MEASURE_RE.match(probe or "")
+    if m:
+        return Probe(kind=MEASURE, src=m.group(1), metric=m.group(2),
+                     op=m.group(3), value=float(m.group(4)))
+    raise ProbeError(f"cannot parse probe: {probe!r}")
+
+
+_OPS = {">=": lambda a, b: a >= b, "<=": lambda a, b: a <= b, ">": lambda a, b: a > b,
+        "<": lambda a, b: a < b, "==": lambda a, b: a == b, "!=": lambda a, b: a != b}
+
+
+def probe_ok(probe: str) -> bool:
+    try:
+        parse(probe)
+        return True
+    except ProbeError:
+        return False
+
+
+def evaluate(probe: str, runner: Runner) -> bool:
+    """Evaluate a probe string against a live runner → the boolean fact.
+
+    The `all` quantifier only means something to a TYPE-resolving runner (one token can name many
+    devices). A plain name-based runner has exactly one pair, so `all` and `any` coincide and it
+    can simply not implement `*_all` — hence the getattr fallback rather than a protocol break."""
+    p = parse(probe)
+    if p.kind in (REACH, PING):
+        fn = getattr(runner, "reach_all", None) if p.quant == "all" else None
+        got = fn(p.src, p.dst, p.port) if fn else runner.reach(p.src, p.dst, p.port)
+        return got == p.expect_ok
+    if p.kind == HTTP:
+        fn = getattr(runner, "http_all", None) if p.quant == "all" else None
+        port = p.port or 80
+        got = fn(p.src, p.dst, port) if fn else runner.http(p.src, p.dst, port)
+        return got == p.expect_ok
+    if p.kind == BALANCES:
+        return runner.backends(p.src) >= p.n
+    if p.kind == FLOW:
+        return runner.flow(p.src, p.match)
+    if p.kind == MEASURE:
+        got = runner.measure(p.src, p.metric)
+        if got is None:
+            return False                    # no reading yet — treat as not-satisfied, not a crash
+        return _OPS[p.op](got, p.value)
+    raise ProbeError(f"unknown probe kind {p.kind!r}")
+
+
+# -- type-aware resolution (name-agnostic behavioral probes) ---------------- #
+class TypeRunner:
+    """Wraps a name-based `Runner` so a probe's tokens are element TYPE keys, resolved existentially
+    against the live topology — the behavioral analogue of our type-based structural predicates.
+    `reach(web_app -> database)` becomes "SOME web_app device reaches SOME database device", so a
+    behavioral objective matches whatever the student actually named things (exactly like `path`).
+
+    `get_topology()` returns the live topology (anything with `.devices` whose values have
+    `.name`/`.type_key`). Delegates availability to the wrapped runner."""
+
+    def __init__(self, base: Runner, get_topology) -> None:
+        self.base = base
+        self._get_topology = get_topology
+
+    def available(self) -> bool:
+        return bool(self.base) and self.base.available()
+
+    def _names(self, spec: str) -> list[str]:
+        """Names of devices matching `type` or a slot-scoped `type@slot` (cross-slot reach). Slot
+        scope is hierarchical: `host@pods0` includes hosts nested in `pods0_lans1` (see slot_match)."""
+        from .objectives import slot_match
+        type_key, _, slot = str(spec).partition("@")
+        t = self._get_topology()
+        return [d.name for d in getattr(t, "devices", {}).values()
+                if getattr(d, "type_key", None) == type_key
+                and slot_match(getattr(d, "slot", ""), slot)]
+
+    def _pairs(self, src: str, dst: str):
+        """Every (src, dst) name pair — EXCLUDING a device paired with itself. When both tokens are
+        the same type (`reach(host -> host)`, the LAN-repair case) the self-pair would make the
+        probe vacuously true: a host can always ping its own loopback. Proving a host talks to
+        *itself* proves nothing about the network."""
+        for s in self._names(src):
+            for d in self._names(dst):
+                if s != d:
+                    yield s, d
+
+    def reach(self, src: str, dst: str, port: int | None = None) -> bool:
+        return any(self.base.reach(s, d, port) for s, d in self._pairs(src, dst))
+
+    def http(self, src: str, dst: str, port: int) -> bool:
+        return any(self.base.http(s, d, port) for s, d in self._pairs(src, dst))
+
+    # -- universal ("all") resolution --------------------------------------- #
+    # `reach(host -> host, all)` = EVERY host reaches every other. Needed for repair missions: with
+    # the existential reading, one healthy pair would mask a broken third host. An empty pair set is
+    # False, not vacuously True — "no hosts" must never look like "all hosts talk".
+    def reach_all(self, src: str, dst: str, port: int | None = None) -> bool:
+        pairs = list(self._pairs(src, dst))
+        return bool(pairs) and all(self.base.reach(s, d, port) for s, d in pairs)
+
+    def http_all(self, src: str, dst: str, port: int) -> bool:
+        pairs = list(self._pairs(src, dst))
+        return bool(pairs) and all(self.base.http(s, d, port) for s, d in pairs)
+
+    def backends(self, lb: str) -> int:
+        return max((self.base.backends(n) for n in self._names(lb)), default=0)
+
+    def flow(self, ovs: str, match: str) -> bool:
+        return any(self.base.flow(n, match) for n in self._names(ovs))
+
+    def measure(self, rider_type: str, metric: str) -> float | None:
+        # measure is inherently type-based (you assert on "the packet_view" of the fragment) —
+        # delegate straight to the base, which finds a rider of that type and runs it.
+        fn = getattr(self.base, "measure", None)
+        return fn(rider_type, metric) if fn else None
+
+
+# -- a fake runner for tests + offline authoring ---------------------------- #
+class FakeRunner:
+    """A scriptable runner backed by a facts dict — for unit tests and lesson playtests without
+    Docker. Facts keys: ('reach', src, dst, port) -> bool, ('http', src, dst, port) -> bool,
+    ('backends', lb) -> int, ('flow', ovs, match) -> bool."""
+
+    def __init__(self, facts: dict | None = None, available: bool = True,
+                 default: bool = False) -> None:
+        self.facts = facts or {}
+        self._available = available
+        self._default = default          # verdict for unscripted reach/http facts
+
+    def available(self) -> bool:
+        return self._available
+
+    def reach(self, src: str, dst: str, port: int | None = None) -> bool:
+        return bool(self.facts.get(("reach", src, dst, port), self._default))
+
+    def http(self, src: str, dst: str, port: int) -> bool:
+        return bool(self.facts.get(("http", src, dst, port), self._default))
+
+    def backends(self, lb: str) -> int:
+        return int(self.facts.get(("backends", lb), 0))
+
+    def measure(self, rider_type: str, metric: str) -> float | None:
+        return self.facts.get(("measure", rider_type, metric))
+
+    def flow(self, ovs: str, match: str) -> bool:
+        return bool(self.facts.get(("flow", ovs, match), False))