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

gini/domain/staging.py

@@ -0,0 +1,122 @@
+"""Board staging — a lesson can open with part of the canvas already built (M3).
+
+Enables scaffolded labs ("here's a half-built network, finish it") and fault-injection ("I broke the
+routing — fix it"). A lesson's `stage:` is an authorable, self-contained spec of devices + links; on
+mission start the engine builds them onto the canvas. Pure logic (the caller supplies `add_device` /
+`add_link` so it works against the live AppContext in the app and against fakes in tests).
+
+Two kinds of fault can be injected, and the difference matters pedagogically:
+
+  * **Missing element** — something isn't there (`fix-the-lan`: two subnets, no router). The student
+    diagnoses an absence.
+  * **Mis-configuration** — everything is there and *looks* right, but a setting is wrong (a host
+    addressed into the wrong subnet). Nothing is visibly absent, so the picture can't reveal the
+    bug: only *running it* can. This is the harder and more realistic skill, and it's why a
+    mis-config mission must be graded by a live probe, never by structure.
+
+Stage schema (in the lesson YAML):
+
+    stage:
+      reset: true                  # default: clear the canvas first, so the board is exactly this
+      manual_addressing: true      # turn OFF auto-IP, so the addresses below actually stick
+      devices:
+        - {ref: r1, type: router}
+        - {ref: s1, type: switch}
+        - {ref: h1, type: host, x: 100, y: 200,
+           ips: {s1: 10.0.0.10},                 # IP on the interface facing s1  (mis-config knob)
+           properties: {Note: "was working yesterday"}}
+      links:
+        - [h1, s1]        # by ref
+        - [s1, r1]
+
+`ref` is a local handle used only to wire links and address interfaces; it never has to match the
+student's device names. `ips` is keyed by the *peer's ref* — the author says "the leg facing s1" and
+staging resolves it to the real link id once the link exists, because link ids don't exist until the
+board is built.
+"""
+from __future__ import annotations
+
+
+def normalize(stage) -> dict:
+    """Coerce a stage spec into a canonical dict (tolerant of shapes)."""
+    empty = {"devices": [], "links": [], "reset": True, "manual_addressing": False}
+    if not stage or not isinstance(stage, dict):
+        return empty
+    links = []
+    for l in stage.get("links", []) or []:
+        if isinstance(l, (list, tuple)) and len(l) >= 2:
+            links.append([l[0], l[1]])
+        elif isinstance(l, dict) and "source" in l and "target" in l:
+            links.append([l["source"], l["target"]])
+    return {
+        "devices": list(stage.get("devices", []) or []),
+        "links": links,
+        # a staged board is a *designed* board: by default it replaces whatever was on the canvas,
+        # or the mission would grade against elements the author never put there.
+        "reset": bool(stage.get("reset", True)),
+        "manual_addressing": bool(stage.get("manual_addressing", False)),
+    }
+
+
+def is_staged(lesson) -> bool:
+    spec = normalize(getattr(lesson, "stage", None))
+    return bool(spec["devices"])
+
+
+def wants_reset(lesson) -> bool:
+    spec = normalize(getattr(lesson, "stage", None))
+    return bool(spec["devices"]) and spec["reset"]
+
+
+def apply(stage, *, add_device, add_link, topology=None) -> dict:
+    """Build a stage. `add_device(type_key, x, y) -> instance` (with an `.id`); `add_link(src_id,
+    tgt_id)` -> link (with an `.id`; a caller that returns None just forfeits IP injection).
+    Returns {ref -> instance}. Links to an unknown ref are skipped (authoring safety). Never raises
+    on a bad single row — best-effort, because a typo in one stage row must not stop the lesson.
+
+    If `topology` is given and the stage asks for it, manual addressing is switched on — without
+    that the compiler auto-assigns IPs and would silently *repair* the very fault we injected.
+    """
+    spec = normalize(stage)
+    if topology is not None and spec["manual_addressing"]:
+        topology.manual_addressing = True
+
+    placed: dict[str, object] = {}
+    wanted: dict[str, dict] = {}                  # ref -> {peer_ref: ip}
+    for i, d in enumerate(spec["devices"]):
+        tk = d.get("type")
+        if not tk:
+            continue
+        ref = d.get("ref") or d.get("name") or f"{tk}{i}"
+        try:
+            inst = add_device(tk, float(d.get("x", 0) or 0), float(d.get("y", 0) or 0))
+        except Exception:
+            continue
+        placed[ref] = inst
+        props = d.get("properties") or {}
+        if props and hasattr(inst, "properties"):
+            inst.properties.update({str(k): str(v) for k, v in props.items()})
+        ips = d.get("ips") or {}
+        if ips:
+            wanted[ref] = {str(k): str(v) for k, v in ips.items()}
+
+    for a, b in spec["links"]:
+        da, db = placed.get(a), placed.get(b)
+        if da is None or db is None:
+            continue
+        try:
+            link = add_link(da.id, db.id)
+        except Exception:
+            continue
+        lid = getattr(link, "id", None)
+        if lid is None:
+            continue
+        # now that the link exists we can pin each authored IP to the right leg: the author writes
+        # "on h1, the interface facing s1", i.e. wanted[near_ref][far_ref].
+        for near_ref, far_ref in ((a, b), (b, a)):
+            ip = (wanted.get(near_ref) or {}).get(far_ref)
+            near = placed[near_ref]
+            if ip and hasattr(near, "static_ips"):
+                near.static_ips[lid] = ip
+
+    return placed

gini/domain/syscall_builder.py

@@ -0,0 +1,144 @@
+"""Syscall builder — turn a student's syscall spec into the real xv6 (RISC-V) edits.
+
+Adding a system call to xv6 touches five places; this module generates all of them from a
+small spec (name, return type, args, C body). It is PURE text generation, so the codegen and
+validation are unit-tested without a compiler — the actual write-patches-and-recompile step is
+Mac-side (xv6 tree + `make`), exactly the same split as the rest of the Machine Lab.
+
+The five edit sites (xv6-riscv, MIT 6.1810):
+  1. kernel/syscall.h  — `#define SYS_<name> <n>`
+  2. kernel/syscall.c  — `extern uint64 sys_<name>(void);` + `[SYS_<name>] sys_<name>,`
+  3. kernel/sysproc.c  — the `uint64 sys_<name>(void){…}` implementation (with arg fetch)
+  4. user/user.h       — the user-facing prototype
+  5. user/usys.pl      — `entry("<name>");` (generates the usys.S trampoline)
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+# The stock xv6-riscv system calls (numbers 1..21), used to reject name collisions and to
+# compute the next free syscall number.
+# current xv6-riscv: fork=1 .. sync=22 (note `pause`, not `sleep`, and `sync` at 22)
+STOCK_SYSCALLS = (
+    "fork", "exit", "wait", "pipe", "read", "kill", "exec", "fstat", "chdir", "dup",
+    "getpid", "sbrk", "pause", "uptime", "open", "write", "mknod", "unlink", "link",
+    "mkdir", "close", "sync",
+)
+NEXT_FREE_NUMBER = len(STOCK_SYSCALLS) + 1        # 23
+
+ARG_TYPES = ("int", "addr", "str")               # how the arg is fetched in the kernel
+RET_TYPES = ("int", "uint64", "void")
+
+_IDENT = re.compile(r"^[a-z_][a-z0-9_]*$")
+# user.h C type shown to the student, per kernel arg type
+_USER_CTYPE = {"int": "int", "addr": "void*", "str": "const char*"}
+
+
+@dataclass
+class SyscallArg:
+    name: str
+    type: str = "int"        # one of ARG_TYPES
+
+
+@dataclass
+class SyscallSpec:
+    name: str
+    ret: str = "uint64"
+    args: list = field(default_factory=list)      # [SyscallArg]
+    body: str = "  return 0;"
+
+
+def validate(spec: SyscallSpec, existing=STOCK_SYSCALLS) -> list[str]:
+    """Return a list of human error strings ([] == valid)."""
+    errs: list[str] = []
+    if not spec.name or not _IDENT.match(spec.name):
+        errs.append("Name must be a valid C identifier (lower-case letters, digits, '_').")
+    elif spec.name in existing:
+        errs.append(f"'{spec.name}' is already an xv6 system call — pick another name.")
+    if spec.ret not in RET_TYPES:
+        errs.append(f"Return type must be one of {', '.join(RET_TYPES)}.")
+    if len(spec.args) > 6:
+        errs.append("A system call can take at most 6 arguments (registers a0–a5).")
+    seen = set()
+    for a in spec.args:
+        if not a.name or not _IDENT.match(a.name):
+            errs.append(f"Argument name '{a.name}' is not a valid C identifier.")
+        elif a.name in seen:
+            errs.append(f"Duplicate argument name '{a.name}'.")
+        seen.add(a.name)
+        if a.type not in ARG_TYPES:
+            errs.append(f"Argument '{a.name}' has an unknown type '{a.type}'.")
+    if not (spec.body or "").strip():
+        errs.append("The C body is empty — add what the system call should do.")
+    elif spec.ret != "void" and "return" not in spec.body:
+        errs.append("The body has no `return` but the return type isn't void.")
+    return errs
+
+
+def _fetch(arg: SyscallArg, i: int) -> str:
+    if arg.type == "int":
+        return f"  int {arg.name};\n  argint({i}, &{arg.name});"
+    if arg.type == "addr":
+        return f"  uint64 {arg.name};\n  argaddr({i}, &{arg.name});"
+    return (f"  char {arg.name}[128];\n"
+            f"  argstr({i}, {arg.name}, sizeof({arg.name}));")
+
+
+@dataclass
+class Codegen:
+    number: int
+    syscall_h: str          # #define line
+    extern: str             # extern decl for syscall.c
+    dispatch: str           # dispatch-table row for syscall.c
+    impl: str               # the sys_<name> function for sysproc.c
+    user_h: str             # user-space prototype
+    usys_entry: str         # entry("<name>");
+
+    def files(self) -> list[tuple[str, str, str]]:
+        """(path, where, snippet) for each of the five edit sites."""
+        return [
+            ("kernel/syscall.h", "add the #define", self.syscall_h),
+            ("kernel/syscall.c", "add extern + dispatch row",
+             self.extern + "\n" + self.dispatch),
+            ("kernel/sysproc.c", "append the implementation", self.impl),
+            ("user/user.h", "add the prototype", self.user_h),
+            ("user/usys.pl", "add the entry", self.usys_entry),
+        ]
+
+    def preview(self) -> str:
+        return "\n\n".join(f"/* {path} — {where} */\n{snippet}"
+                           for path, where, snippet in self.files())
+
+
+def generate(spec: SyscallSpec, number: int = NEXT_FREE_NUMBER) -> Codegen:
+    """Render the five edits for `spec`. Assumes `spec` already validated."""
+    name = spec.name
+    fetch = "\n".join(_fetch(a, i) for i, a in enumerate(spec.args))
+    body = spec.body if spec.body.strip() else "  return 0;"
+    impl_lines = [f"uint64", f"sys_{name}(void)", "{"]
+    if fetch:
+        impl_lines.append(fetch)
+    impl_lines += ["  // ---- your code ----", body.rstrip(), "  // -------------------", "}"]
+    impl = "\n".join(impl_lines)
+
+    user_args = ", ".join(f"{_USER_CTYPE[a.type]} {a.name}" for a in spec.args) or "void"
+    user_ret = "int" if spec.ret in ("int", "uint64") else "int"   # xv6 user.h convention
+
+    return Codegen(
+        number=number,
+        syscall_h=f"#define SYS_{name} {number}",
+        extern=f"extern uint64 sys_{name}(void);",
+        dispatch=f"[SYS_{name}] sys_{name},",
+        impl=impl,
+        user_h=f"{user_ret} {name}({user_args});",
+        usys_entry=f'entry("{name}");',
+    )
+
+
+def starter_body(spec_name: str = "") -> str:
+    """A friendly starter the builder pre-fills the body editor with."""
+    return ("  // read your args above, do the work, and return a value.\n"
+            "  // e.g. print from the kernel:\n"
+            '  printf("hello from sys_' + (spec_name or "mycall") + '\\n");\n'
+            "  return 0;")

gini/domain/topic_cloud.py

@@ -0,0 +1,62 @@
+"""The Ask GINI topic cloud — an inviting, clickable set of things a student can explore or
+build, generated from the live GINI knowledge base (concept notes, recipes, a few marquee
+elements). Tapping a term SENDS the matching question/build to Ask GINI, so the cloud both
+sparks ideas AND nudges the student toward vocabulary the (lexical) retriever lands on.
+
+Framed as an invitation, not a cage — "GINI's great at these, or ask anything." Pure/data so
+the cloud content is unit-tested; the UI renders these `CloudItem`s as a flow of pills.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import concepts as _concepts
+from . import recipes as _recipes
+from .devices import REGISTRY
+
+# a colour rotation so the cloud looks lively (theme accent keys)
+_ACCENTS = ["blue", "green", "purple", "teal", "indigo", "amber", "pink", "cyan", "orange"]
+# recognisable elements worth a small pill (concepts + recipes carry the rest)
+_MARQUEE = ["router", "switch", "firewall", "load_balancer", "function", "database",
+            "vnf", "ovs", "container", "pod"]
+
+
+@dataclass
+class CloudItem:
+    label: str          # what's shown on the pill
+    kind: str           # concept | recipe | element
+    query: str          # sent to Ask GINI when the pill is tapped
+    weight: int         # 1..3 → font-size tier (concepts biggest)
+    accent: str         # theme accent key for colour
+
+
+def _short(c) -> str:
+    """A punchy label for a concept — its canonical keyword, cased (acronyms upper)."""
+    w = (c.keywords[0] if c.keywords else c.title)
+    return w.upper() if len(w) <= 3 else w[:1].upper() + w[1:]
+
+
+def _pill(text: str, cap: int = 22) -> str:
+    """A tidy pill label: drop parentheticals and clip, so the cloud stays a cloud of
+    short punchy words (the full name still goes in the query for retrieval)."""
+    import re
+    text = re.sub(r"\s*\([^)]*\)", "", text).strip()
+    return text if len(text) <= cap else text[: cap - 1].rstrip() + "…"
+
+
+def topic_cloud() -> list[CloudItem]:
+    """Every explorable/buildable topic, as pills. Concepts → 'explain X' (big), recipes →
+    'show me an X' build (medium), marquee elements → 'what is a X' (small)."""
+    items: list[CloudItem] = []
+    for i, c in enumerate(_concepts.CONCEPTS):
+        lbl = _short(c)
+        items.append(CloudItem(lbl, "concept", f"explain {lbl}", 3, _ACCENTS[i % len(_ACCENTS)]))
+    for r in _recipes.RECIPES:
+        items.append(CloudItem(_pill(r.name), "recipe",
+                               f"show me a {r.name} example", 2, "green"))
+    for key in _MARQUEE:
+        dt = REGISTRY.get(key)
+        if dt is not None:
+            items.append(CloudItem(_pill(dt.label), "element", f"what is a {dt.label}?", 1,
+                                   getattr(dt.accent, "value", "slate")))
+    return items

gini/domain/topology.py

@@ -0,0 +1,213 @@
+"""In-memory topology model (pure Python, no Qt).
+
+This is the single source of truth for what's on the canvas. The UI renders it,
+the compiler/persistence layers read it, and the AI agent layer mutates it.
+"""
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass, field, asdict
+
+from . import devices
+from .devices import DeviceType
+
+
+@dataclass
+class DeviceInstance:
+    id: str
+    type_key: str
+    name: str
+    x: float = 0.0
+    y: float = 0.0
+    parent_id: str | None = None
+    properties: dict[str, str] = field(default_factory=dict)
+    # manual addressing: link_id -> static IPv4 (bare dotted-quad). Only honored when
+    # the topology is in manual_addressing mode; empty/missing entries auto-fill.
+    static_ips: dict[str, str] = field(default_factory=dict)
+    # instance "size" tier (1=S … 4=XL) for resizable elements — bigger = more vCPU/mem
+    # and proportionally more GINI $/hr. See domain/pricing.py SIZE_TIERS.
+    size: int = 1
+    # for container elements (VPC/Subnet/Region): the box's drawn size on the canvas.
+    # 0 = use the type's default; non-container elements ignore these.
+    w: float = 0.0
+    h: float = 0.0
+    # composition slot this device belongs to (a scaffold/bound dependency, e.g. "A"). Empty = the
+    # fragment's own delta. Predicates reference it as `type@slot`.
+    slot: str = ""
+    # WHICH fragment was materialized into that slot (e.g. "cap-lan"). Provenance only — no predicate
+    # reads it; it exists so the canvas can label a slot group with what actually fills it
+    # ("nets · cap-lan ×4") instead of just a count, and so a composed board is self-describing.
+    slot_source: str = ""
+
+    @property
+    def type(self) -> DeviceType:
+        return devices.get(self.type_key)
+
+
+@dataclass
+class Link:
+    id: str
+    source_id: str
+    target_id: str
+    label: str = ""
+    # "link" = a network cable (carries traffic, compiled to real wiring).
+    # "attach" = a rider→donor mount: a Source/Sink runs ON the donor. Carries no traffic and is
+    # NOT compiled as a cable — a "runs on" relationship, drawn dotted. source_id is the rider.
+    kind: str = "link"
+
+
+class Topology:
+    """A graph of device instances and the links between them."""
+
+    def __init__(self, name: str = "untitled") -> None:
+        self.name = name
+        self.devices: dict[str, DeviceInstance] = {}
+        self.links: dict[str, Link] = {}
+        # when True the compiler stops auto-assigning IPs and honors each device's
+        # static_ips, auto-filling any interface left blank.
+        self.manual_addressing: bool = False
+        self._ids = itertools.count(1)
+        self._name_counters: dict[str, int] = {}
+        # per-type auto-name prefix overrides (type_key -> prefix), set from Settings;
+        # empty means use the curated DEFAULT_PREFIXES (R1, S1, M1, …).
+        self.prefix_overrides: dict[str, str] = {}
+
+    # -- creation ----------------------------------------------------------- #
+    def _new_id(self, prefix: str) -> str:
+        return f"{prefix}{next(self._ids)}"
+
+    def _auto_name(self, dt: DeviceType) -> str:
+        # prefix: a user override (e.g. "Mach_"), else the curated default (M, R, S, …)
+        base = self.prefix_overrides.get(dt.key) or devices.default_prefix(dt.key)
+        n = self._name_counters.get(base, 0) + 1
+        self._name_counters[base] = n
+        return f"{base}{n}"
+
+    def add_device(
+        self,
+        type_key: str,
+        name: str | None = None,
+        x: float = 0.0,
+        y: float = 0.0,
+        parent_id: str | None = None,
+        properties: dict[str, str] | None = None,
+    ) -> DeviceInstance:
+        dt = devices.get(type_key)
+        name = name or self._auto_name(dt)
+        props = dict(dt.default_properties)
+        if properties:
+            props.update(properties)
+        props["Name"] = name
+        inst = DeviceInstance(
+            id=self._new_id(dt.key + "-"),
+            type_key=type_key,
+            name=name,
+            x=x,
+            y=y,
+            parent_id=parent_id,
+            properties=props,
+        )
+        self.devices[inst.id] = inst
+        return inst
+
+    def add_link(self, source_id: str, target_id: str, label: str = "") -> Link:
+        if source_id not in self.devices or target_id not in self.devices:
+            raise KeyError("link endpoints must be existing devices")
+        link = Link(self._new_id("link-"), source_id, target_id, label)
+        self.links[link.id] = link
+        return link
+
+    def add_attach(self, rider_id: str, donor_id: str, label: str = "") -> Link:
+        """Mount a rider (Source/Sink) onto its donor. Distinct from a network link: it carries no
+        traffic and is not compiled — the rider merely RUNS ON the donor. `rider_id` is source_id."""
+        if rider_id not in self.devices or donor_id not in self.devices:
+            raise KeyError("attach endpoints must be existing devices")
+        link = Link(self._new_id("attach-"), rider_id, donor_id, label, kind="attach")
+        self.links[link.id] = link
+        return link
+
+    # -- mutation ----------------------------------------------------------- #
+    def remove_device(self, device_id: str) -> None:
+        self.devices.pop(device_id, None)
+        for lid in [l.id for l in self.links.values()
+                    if l.source_id == device_id or l.target_id == device_id]:
+            self.links.pop(lid, None)
+
+    def rename(self, device_id: str, name: str) -> None:
+        d = self.devices[device_id]
+        d.name = name
+        d.properties["Name"] = name
+
+    # -- queries ------------------------------------------------------------ #
+    def find_by_name(self, name: str) -> DeviceInstance | None:
+        for d in self.devices.values():
+            if d.name == name:
+                return d
+        return None
+
+    def neighbors(self, device_id: str) -> list[DeviceInstance]:
+        out = []
+        for l in self.links.values():
+            if l.source_id == device_id:
+                out.append(self.devices[l.target_id])
+            elif l.target_id == device_id:
+                out.append(self.devices[l.source_id])
+        return out
+
+    def degree(self, device_id: str) -> int:
+        return sum(1 for l in self.links.values()
+                   if device_id in (l.source_id, l.target_id))
+
+    # -- riders / attach edges ---------------------------------------------- #
+    def net_links(self) -> list["Link"]:
+        """Only the network cables — what the compiler wires. Attach edges are excluded."""
+        return [l for l in self.links.values() if l.kind != "attach"]
+
+    def donor_of(self, rider_id: str) -> "DeviceInstance | None":
+        """The donor a rider is mounted on (the far end of its attach edge), or None."""
+        for l in self.links.values():
+            if l.kind == "attach" and l.source_id == rider_id:
+                return self.devices.get(l.target_id)
+        return None
+
+    def riders_on(self, donor_id: str) -> list["DeviceInstance"]:
+        """Every Source/Sink rider mounted on this donor."""
+        return [self.devices[l.source_id] for l in self.links.values()
+                if l.kind == "attach" and l.target_id == donor_id
+                and l.source_id in self.devices]
+
+    def counts_by_category(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for d in self.devices.values():
+            cat = d.type.category.value
+            out[cat] = out.get(cat, 0) + 1
+        return out
+
+    # -- serialization (used by persistence + agent layer) ------------------ #
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "manual_addressing": self.manual_addressing,
+            "devices": [asdict(d) for d in self.devices.values()],
+            "links": [asdict(l) for l in self.links.values()],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Topology":
+        t = cls(data.get("name", "untitled"))
+        t.manual_addressing = bool(data.get("manual_addressing", False))
+        max_n = 0
+        for d in data.get("devices", []):
+            inst = DeviceInstance(**d)
+            t.devices[inst.id] = inst
+            for token in inst.id.replace("-", " ").split():
+                if token.isdigit():
+                    max_n = max(max_n, int(token))
+        for l in data.get("links", []):
+            link = Link(**l)
+            t.links[link.id] = link
+        t._ids = itertools.count(max_n + 1)
+        return t
+
+    def __repr__(self) -> str:
+        return f"<Topology {self.name!r}: {len(self.devices)} devices, {len(self.links)} links>"

gini/domain/vocabulary.py

@@ -0,0 +1,51 @@
+"""The engine's vocabulary — the discovery protocol (GINI_AUTHORING_DESIGN.md, "Discover").
+
+A single, versioned manifest of everything a fragment can be built FROM on this engine: elements (+
+their grammar), predicates, probes, and capability roles. gBuilder exports it; the Teaching Center
+consumes it so it composes against a *declared version* rather than importing the live engine. This
+is the forward-extensibility seam: when the engine gains a primitive, the exported vocabulary grows,
+and authoring/composition see it automatically — no author-tool code change.
+"""
+from __future__ import annotations
+
+from . import capabilities as _caps
+from . import devices as _devices
+from .content import ENGINE_VERSION, FRAGMENT_SCHEMA
+from .objectives import _TYPE_ARG_FUNCS
+
+
+def export() -> dict:
+    """The full vocabulary manifest for this engine version."""
+    elements = []
+    for d in _devices.all_devices():
+        cat = getattr(d, "category", None)
+        elements.append({"key": d.key, "label": d.label,
+                         "category": str(getattr(cat, "value", cat) or "")})
+    return {
+        "engine_version": ENGINE_VERSION,
+        "schema_version": FRAGMENT_SCHEMA,
+        "elements": sorted(elements, key=lambda e: e["key"]),
+        # structural predicates that take element type_keys as args
+        "predicates": sorted(_TYPE_ARG_FUNCS),
+        # behavioral probes the runtime can witness (measure = a Source/Sink measurement assertion)
+        "probes": ["reach", "ping", "http", "balances", "flow_installed", "measure"],
+        # capability roles (the provides/requires vocabulary), as an is-a map
+        "capabilities": dict(sorted(_caps.PARENTS.items())),
+    }
+
+
+def is_compatible(fragment_engine: str) -> tuple[bool, str]:
+    """Coarse version gate: can content authored on `fragment_engine` be trusted here? Empty = a
+    built-in (always fine). The FINE gate is validation against the real vocabulary (an unknown
+    primitive fails); this is the friendly up-front check + message."""
+    if not fragment_engine or fragment_engine == ENGINE_VERSION:
+        return True, ""
+    try:
+        theirs = tuple(int(x) for x in fragment_engine.split("."))
+        ours = tuple(int(x) for x in ENGINE_VERSION.split("."))
+    except ValueError:
+        return True, ""                          # unparseable → let validation be the judge
+    if theirs > ours:
+        return False, (f"authored on gBuilder {fragment_engine}, but this is {ENGINE_VERSION} — "
+                       f"update the engine to use it")
+    return True, ""                              # older content is fine (this engine is a superset)