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

gini/domain/connection_rules.py

@@ -0,0 +1,269 @@
+"""Connection grammar — what can wire to what, and *why*.
+
+A single declarative table of the meaningful connections between element types, each
+with a one-line, student-facing reason and whether the link is *required* for one side
+to do its job (e.g. a Pod needs a Cluster to run in). This is pure data with no Qt or
+compiler dependency so every layer can share one source of truth:
+
+  • **X-ray** (long-press a node) highlights its compatible partners + shows the *why*.
+  • **Explain** can answer "what can I connect this to, and what's missing?".
+  • **Wizard / lint** can validate a topology and suggest the next element.
+
+The grammar is intentionally *advisory*, not a hard constraint: gBuilder still lets a
+student wire anything (mistakes are teachable). It just makes the good paths visible.
+
+Edges are undirected for matching purposes; the `why` is phrased to read sensibly from
+either end. `requires` names the element type(s) that genuinely *need* such an edge.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from . import devices as _dev
+
+# Reusable groups (expanded into concrete edges at import). Keep these aligned with the
+# device registry keys.
+GROUPS: dict[str, tuple[str, ...]] = {
+    "WORKLOAD": ("web_app", "instance", "container"),       # VM-style cloud app runtimes
+    "BACKEND": ("web_app", "instance", "container", "pod"),  # things traffic targets
+    "DATASTORE": ("database", "nosql", "cache"),
+    # anything that runs app code — a Pod is a real workload too, so it can use data
+    # stores, emit metrics/traces, and talk to streams/queues just like a Web App.
+    "APPISH": ("web_app", "instance", "container", "function", "pod"),
+}
+
+# Each row: (a, b, why, requires). `a`/`b` may be a GROUP name (uppercase). `requires` is
+# a tuple of type_keys (or group names) for which this edge is *required* to function.
+_SPEC: tuple[tuple[str, str, str, tuple[str, ...]], ...] = (
+    # ---- classic networking ---------------------------------------------- #
+    ("host", "switch", "Join a LAN — a switch links machines on the same subnet.", ()),
+    ("host", "hub", "Share one collision domain (teaching: watch flooding & collisions).", ()),
+    ("host", "router", "Attach a machine straight to a router as its gateway off the LAN.", ()),
+    ("host", "wap", "Join the network over Wi-Fi.", ()),
+    # a graphical Desktop is a real networked host — same LAN connectivity as `host`.
+    ("desktop", "switch", "Join a LAN — the graphical host sits on a subnet like any machine.", ()),
+    ("desktop", "hub", "Share one collision domain (watch flooding & collisions).", ()),
+    ("desktop", "router", "Attach the graphical host straight to a router as its gateway.", ()),
+    ("desktop", "wap", "Join the network over Wi-Fi.", ()),
+    ("switch", "router", "Uplink the LAN to a router so it can reach other subnets.", ()),
+    ("switch", "switch", "Extend the LAN onto a second switch.", ()),
+    ("hub", "switch", "Bridge a shared-media segment into a switched LAN.", ()),
+    ("wap", "switch", "Uplink the access point into the wired LAN.", ()),
+    ("router", "router", "Link routers for multi-hop routing between subnets.", ()),
+    ("router", "cloud", "Reach the public Internet through this router.", ()),
+    ("router", "firewall", "Filter traffic between trust zones with a firewall.", ()),
+    ("firewall", "cloud", "Guard the boundary between the LAN and the Internet.", ()),
+
+    # ---- real hardware in the loop (GINI32) ------------------------------- #
+    # The board is a gateway for the physical devices behind its radio, so it wires
+    # into the topology exactly where a router or a LAN does.
+    ("gini32", "router", "Bring real devices behind the board into this router's subnet.", ()),
+    ("gini32", "switch", "Put the board's real devices on this LAN.", ()),
+
+    # ---- NFV / service function chaining --------------------------------- #
+    # A VNF is an inline network function: it sits BETWEEN two elements in the path, so it
+    # wires to hosts, switches, routers, the OVS, the Internet, and other VNFs (a chain).
+    ("vnf", "host", "Put this network function inline in front of a machine.", ()),
+    ("vnf", "switch", "Insert this network function on the path through a switch.", ()),
+    ("vnf", "router", "Chain this network function to a router in the path.", ()),
+    ("vnf", "ovs", "Attach this VNF to the SDN switch (steer flows through it).", ()),
+    ("vnf", "firewall", "Chain this VNF next to a firewall in the path.", ()),
+    ("vnf", "cloud", "Put this network function at the edge, before the Internet.", ()),
+    ("vnf", "vnf", "Chain VNFs in series — a Service Function Chain (e.g. firewall → IDS).", ()),
+
+    # ---- software-defined networking ------------------------------------- #
+    ("ovs", "controller", "An OpenFlow switch needs a controller to program its flow rules.",
+     ("ovs",)),
+    ("ovs", "host", "Attach end machines to the SDN switch.", ()),
+    ("ovs", "ovs", "Build a multi-switch SDN fabric.", ()),
+
+    # ---- containers & Kubernetes ----------------------------------------- #
+    ("pod", "k8s_cluster", "A Pod needs a Cluster to run in — this is where it deploys.",
+     ("pod",)),
+    ("pod", "instance_group", "Add a Pod Autoscaler (HPA) to scale this Pod's replicas on CPU.",
+     ("instance_group",)),
+    ("pod", "registry", "Pull the Pod's image from a private registry.", ()),
+    ("k8s_cluster", "registry", "Serve images to the cluster's workloads from a registry.", ()),
+
+    # ---- traffic into backends (LB / proxy / load-gen) ------------------- #
+    ("load_balancer", "BACKEND", "Distribute incoming traffic across this backend.", ()),
+    ("proxy", "BACKEND", "Front this service with a reverse proxy (routing / TLS).", ()),
+    ("load_generator", "BACKEND", "Fire HTTP load at this app to test it under traffic.", ()),
+    ("load_balancer", "proxy", "Chain a load balancer in front of a reverse proxy.", ()),
+
+    # ---- apps + their data (a Pod is an app too, so it's a BACKEND here) -- #
+    ("BACKEND", "DATASTORE", "Back this app with a database / cache for its state.", ()),
+    ("BACKEND", "object_store", "Store & serve files / objects for this app.", ()),
+    ("instance", "block_volume", "Attach a persistent disk to this instance.",
+     ("block_volume",)),
+
+    # ---- cloud networking ------------------------------------------------ #
+    ("vpc", "cloud_subnet", "A VPC is divided into subnets — place this subnet inside it.",
+     ("cloud_subnet",)),
+    ("cloud_subnet", "WORKLOAD", "Place this workload inside the subnet.", ()),
+    ("security_group", "WORKLOAD", "Attach a stateful firewall to this workload.", ()),
+    ("security_group", "DATASTORE", "Lock down this datastore — allow only the tiers you list.", ()),
+    ("gateway", "vpc", "Give the VPC outbound Internet through this gateway.", ()),
+    ("gateway", "cloud", "The gateway faces the public Internet.", ()),
+
+    # ---- serverless ------------------------------------------------------ #
+    ("api_gateway", "function", "Route a URL path to this function (the front door).", ()),
+    ("function", "DATASTORE", "Read & write state from the function (it's stateless itself).", ()),
+    ("function", "object_store", "Read & write objects from the function.", ()),
+    ("function", "queue", "Trigger the function from queue messages (event-driven).", ()),
+    ("function", "stream", "Trigger the function from an event stream.", ()),
+    ("function", "messaging", "Trigger the function from pub/sub messages.", ()),
+    ("api_gateway", "web_app", "Front a web service with a managed API.", ()),
+    ("load_generator", "api_gateway", "Fire HTTP load at the gateway to watch functions scale.", ()),
+    ("load_generator", "function", "Invoke the function under load to test it.", ()),
+    ("metrics", "function", "Scrape invocation metrics from the function runtime.", ()),
+    ("metrics", "api_gateway", "Scrape request metrics from the API gateway.", ()),
+    ("queue", "WORKLOAD", "Pass messages asynchronously between services.", ()),
+
+    # ---- VM-vs-container experiment (Kata Instance) ---------------------- #
+    # A deliberately RESTRICTED set: a Kata Instance is a VM-isolated workload used only
+    # for the isolation experiment, so it wires to a load source, a backend, and metrics —
+    # never k8s, the networking plane, or VPCs (it can't run those / stays flat).
+    ("load_generator", "kinstance", "Fire HTTP load at the VM workload to measure it.", ()),
+    ("load_balancer", "kinstance", "Fan traffic across several VM workloads.", ()),
+    ("kinstance", "DATASTORE", "Back the VM workload with a database / cache.", ()),
+    ("kinstance", "object_store", "Read & write objects from the VM workload.", ()),
+    ("metrics", "kinstance", "Scrape metrics from the VM workload.", ()),
+    ("kinstance", "kinstance", "Build a multi-VM topology to compare against containers.", ()),
+
+    # ---- streaming & messaging ------------------------------------------- #
+    ("stream", "APPISH", "Produce / consume an event log with this service.", ()),
+    ("messaging", "APPISH", "Publish / subscribe messages with this service.", ()),
+
+    # ---- observability --------------------------------------------------- #
+    ("metrics", "BACKEND", "Scrape metrics from this target.", ()),
+    ("metrics", "proxy", "Scrape request metrics from the proxy.", ()),
+    ("metrics", "load_balancer", "Scrape metrics from the load balancer.", ()),
+    ("dashboard", "metrics", "A dashboard needs a metrics source to visualize.", ("dashboard",)),
+    ("tracing", "APPISH", "Collect distributed traces from this service.", ()),
+
+    # ---- xv6 peripherals (xv6 has NO networking; you attach software devices) --- #
+    ("xv6", "terminal", "Attach a Terminal to type commands and watch xv6's console.", ()),
+    ("xv6", "storage_volume", "Attach the xv6 disk to inspect its file system.", ()),
+)
+
+
+# xv6 has no network stack, so unlike the advisory grammar above these ARE hard constraints:
+# an xv6 Machine wires ONLY to its peripherals, and a peripheral wires ONLY to an xv6 Machine.
+_XV6_PERIPHERALS = frozenset({"terminal", "storage_volume"})
+
+
+# --------------------------------------------------------------------------- #
+# Attach grammar: riders (Sources / Sinks) mount onto a donor, they don't wire.
+# --------------------------------------------------------------------------- #
+def is_rider(type_key: str) -> bool:
+    dt = _dev.REGISTRY.get(type_key)
+    return bool(dt and getattr(dt, "rider", False))
+
+
+def attach_targets(rider_type: str) -> tuple[str, ...]:
+    """The donor type_keys a rider may ride (empty if it isn't a rider)."""
+    dt = _dev.REGISTRY.get(rider_type)
+    return tuple(getattr(dt, "attaches_to", ()) or ()) if dt else ()
+
+
+def riders_for(donor_type: str) -> list[str]:
+    """Every rider type that can mount on this donor (drives X-ray from the donor's side)."""
+    return sorted(k for k, dt in _dev.REGISTRY.items()
+                  if getattr(dt, "rider", False)
+                  and donor_type in (getattr(dt, "attaches_to", ()) or ()))
+
+
+def attach_blocked(rider_type: str, donor_type: str) -> str | None:
+    """A reason to REJECT mounting `rider_type` on `donor_type`, or None to allow it."""
+    if not is_rider(rider_type):
+        return "Only a Source or Sink can be attached — wire the rest as network links."
+    if is_rider(donor_type):
+        return "A donor can't be another Source/Sink — attach the rider to a Machine, Router, …"
+    if donor_type not in attach_targets(rider_type):
+        tgts = ", ".join(attach_targets(rider_type)) or "a compatible element"
+        return f"A {rider_type} attaches to {tgts} — not {donor_type}."
+    return None
+
+
+def link_blocked(a: str, b: str) -> str | None:
+    """A reason to REJECT an a–b link (a HARD constraint), or None to allow it."""
+    # A Source/Sink rides its donor with a dotted ATTACH edge, never a network cable.
+    for x, other in ((a, b), (b, a)):
+        if is_rider(x):
+            return (f"A {x} is a Source/Sink — attach it to its donor (dotted), don't wire it as "
+                    f"a network link.")
+    if a == "xv6" or b == "xv6":
+        other = b if a == "xv6" else a
+        if other != "xv6" and other not in _XV6_PERIPHERALS:
+            return ("xv6 has no networking — attach a Screen, Keyboard, or Storage Volume "
+                    "instead of a network connection.")
+    if a in _XV6_PERIPHERALS or b in _XV6_PERIPHERALS:
+        other = b if a in _XV6_PERIPHERALS else a
+        if other != "xv6":
+            return "An xv6 peripheral attaches only to an xv6 Machine."
+    return None
+
+
+@dataclass(frozen=True)
+class Partner:
+    """A valid connection partner for some element, with its teaching reason."""
+    type_key: str
+    why: str
+    required: bool        # True if the *queried* element needs at least one such link
+
+
+def _expand(name: str) -> tuple[str, ...]:
+    return GROUPS.get(name, (name,))
+
+
+# adjacency: type_key -> {partner_type: (why, requires_set)}; built once at import.
+_ADJ: dict[str, dict[str, tuple[str, frozenset]]] = {}
+
+
+def _add(a: str, b: str, why: str, requires: frozenset) -> None:
+    cur = _ADJ.setdefault(a, {}).get(b)
+    # keep the first reason but union requirements (a pair may appear via several rows)
+    if cur is None:
+        _ADJ[a][b] = (why, requires)
+    else:
+        _ADJ[a][b] = (cur[0], cur[1] | requires)
+
+
+for _a, _b, _why, _req in _SPEC:
+    _reqset = frozenset(t for r in _req for t in _expand(r))
+    for ea in _expand(_a):
+        for eb in _expand(_b):
+            _add(ea, eb, _why, _reqset)
+            if ea != eb:
+                _add(eb, ea, _why, _reqset)
+
+
+def partners_for(type_key: str) -> list[Partner]:
+    """Every element type `type_key` can meaningfully connect to, required ones first."""
+    out = [Partner(p, why, type_key in req)
+           for p, (why, req) in _ADJ.get(type_key, {}).items()]
+    out.sort(key=lambda p: (not p.required, p.type_key))
+    return out
+
+
+def partner_types(type_key: str) -> set[str]:
+    """Just the set of compatible partner type keys (for fast highlight tests)."""
+    return set(_ADJ.get(type_key, {}).keys())
+
+
+def can_connect(a: str, b: str) -> str | None:
+    """The teaching reason for an a–b link, or None if it isn't a recommended connection."""
+    edge = _ADJ.get(a, {}).get(b)
+    return edge[0] if edge else None
+
+
+def required_partners(type_key: str) -> list[Partner]:
+    """Partner types this element *needs* at least one of to function."""
+    return [p for p in partners_for(type_key) if p.required]
+
+
+def missing_required(type_key: str, neighbor_types) -> list[Partner]:
+    """Required partners that are absent from `neighbor_types` (drives lint / hints)."""
+    have = set(neighbor_types)
+    return [p for p in required_partners(type_key) if p.type_key not in have]

gini/domain/constraints.py

@@ -0,0 +1,153 @@
+"""DOs / DON'Ts for a described mission — the student's explicit *negative* intent.
+
+The composer must honour "…but no metrics or dashboards": otherwise the auto-filled enrichment layers
+put things on the board the student explicitly refused. We extract an `Excludes` set (roles / element
+types / layers to leave OUT) two ways and merge them:
+
+  • a deterministic **negation scan** of the intent text (reliable, model-free) — catches "no X",
+    "without X", "don't add X", "skip X", across an "and" list;
+  • the reasoning model's own `exclude:` list (belt-and-suspenders, mapped through the same table).
+
+Only *optional* things are excludable (the enrichment layers + their elements) — core network pieces
+(firewall, router, switch, host, internet, LAN) are deliberately NOT here, so "hide it from the
+Internet" can never be misread as "remove the Internet". Assembly then suppresses excluded companions,
+and `compose` reports an **infeasibility** when a thing the student asked FOR inherently needs a thing
+they asked to leave out. Pure data; prune/extend the table as we learn.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .capabilities import ancestors
+from .objectives import element_types_in_check
+
+# keyword (substring, lower) -> (roles, element type_keys, assembly layers) it refers to
+_EXCLUDE_TABLE: dict[str, tuple[tuple[str, ...], tuple[str, ...], tuple[str, ...]]] = {
+    "metric":        (("metrics-source", "metrics-collector"), ("metrics",), ("observe",)),
+    "dashboard":     (("dashboard-view", "visualizer"), ("dashboard",), ("observe",)),
+    "grafana":       (("dashboard-view", "visualizer"), ("dashboard",), ("observe",)),
+    "monitor":       (("visualizer", "metrics-source"), ("metrics", "dashboard"), ("observe",)),
+    "observab":      (("visualizer", "metrics-source"), ("metrics", "dashboard"), ("observe",)),
+    "visuali":       (("visualizer",), (), ("observe",)),
+    "telemetry":     (("metrics-source", "metrics-collector"), ("metrics",), ("observe",)),
+    "load generat":  (("load-generator",), (), ("exercise",)),
+    "load-generat":  (("load-generator",), (), ("exercise",)),
+    "load gen":      (("load-generator",), (), ("exercise",)),
+    "load test":     (("load-generator",), (), ("exercise",)),
+    "load-test":     (("load-generator",), (), ("exercise",)),
+    "traffic gen":   (("traffic-source",), (), ("exercise",)),
+    # "nothing else / no extras / just the network" — leave out ALL enrichment
+    "nothing else":  ((), (), ("exercise", "observe")),
+    "no extras":     ((), (), ("exercise", "observe")),
+    "no extra":      ((), (), ("exercise", "observe")),
+}
+
+# negation cues; the excluded span runs from the cue to the next clause boundary (so "no metrics and
+# dashboards" captures both, but "no metrics but add a router" stops the exclusion at "but").
+_NEG = re.compile(r"\b(no|without|not|don'?t|do not|avoid|skip|exclude|omit|leave out|minus|"
+                  r"except|sans)\b", re.I)
+_STOP = re.compile(r"[.;,]|\b(but|however|while|yet|although|though|and then)\b", re.I)
+
+
+@dataclass
+class Excludes:
+    roles: set[str] = field(default_factory=set)
+    types: set[str] = field(default_factory=set)
+    layers: set[str] = field(default_factory=set)
+
+    def __bool__(self) -> bool:
+        return bool(self.roles or self.types or self.layers)
+
+    def label(self) -> str:
+        """A short human phrase for what was excluded (for the infeasibility / suppression note)."""
+        bits = sorted(self.types) or sorted(self.layers) or sorted(self.roles)
+        return ", ".join(bits)
+
+
+def _add_keyword(ex: Excludes, kw: str) -> None:
+    roles, types, layers = _EXCLUDE_TABLE[kw]
+    ex.roles.update(roles)
+    ex.types.update(types)
+    ex.layers.update(layers)
+
+
+def _negated_text(text: str) -> str:
+    """The concatenation of every span under a negation cue."""
+    spans = []
+    for m in _NEG.finditer(text or ""):
+        rest = text[m.end():]
+        stop = _STOP.search(rest)
+        spans.append(rest[:stop.start()] if stop else rest)
+    return " ".join(spans).lower()
+
+
+def positive_text(text: str) -> str:
+    """The intent with every negated span removed — so a coverage/keyword match can't be triggered by
+    a thing the student said they DON'T want ("no dashboards" must not pull in a dashboard)."""
+    out, idx = [], 0
+    for m in _NEG.finditer(text or ""):
+        out.append(text[idx:m.start()])
+        rest = text[m.end():]
+        stop = _STOP.search(rest)
+        idx = m.end() + (stop.start() if stop else len(rest))
+    out.append(text[idx:])
+    return " ".join(" ".join(out).split())
+
+
+def from_text(text: str) -> Excludes:
+    """Extract DON'Ts from free-form intent by scanning only the NEGATED spans (model-free)."""
+    ex = Excludes()
+    neg = _negated_text(text)
+    for kw in _EXCLUDE_TABLE:
+        if kw in neg:
+            _add_keyword(ex, kw)
+    return ex
+
+
+def from_terms(terms) -> Excludes:
+    """Map an explicit exclude list (e.g. from the model) through the same table — here the terms are
+    already known to be exclusions, so no negation scan is needed."""
+    ex = Excludes()
+    for t in terms or []:
+        low = str(t).lower()
+        for kw in _EXCLUDE_TABLE:
+            if kw in low:
+                _add_keyword(ex, kw)
+    return ex
+
+
+def merge(*exes: Excludes) -> Excludes:
+    out = Excludes()
+    for e in exes:
+        out.roles |= e.roles
+        out.types |= e.types
+        out.layers |= e.layers
+    return out
+
+
+def fragment_excluded(fragment, ex: Excludes) -> bool:
+    """Should this fragment be kept OUT under `ex`? True if its layer is excluded, it provides an
+    excluded capability (matched up the is-a hierarchy), or its objectives place an excluded element."""
+    if not ex:
+        return False
+    if fragment.layer in ex.layers:
+        return True
+    for p in fragment.provides:
+        if ancestors(p) & ex.roles:
+            return True
+    for t in fragment.objectives:
+        if any(et in ex.types for et in element_types_in_check(getattr(t, "check", "") or "")):
+            return True
+    return False
+
+
+def objective_conflicts(objectives, ex: Excludes) -> list[str]:
+    """Excluded element types that STILL appear in the assembled objectives — i.e. a requested core
+    inherently needs something the student asked to leave out (an infeasibility)."""
+    bad: list[str] = []
+    for o in objectives:
+        for et in element_types_in_check(getattr(o, "check", "") or ""):
+            if et in ex.types and et not in bad:
+                bad.append(et)
+    return bad

gini/domain/content.py

@@ -0,0 +1,59 @@
+"""Where fragment content lives on disk — the system layer and the user layer.
+
+Two content roots, so gBuilder can be a packaged app (no source tree) AND have somewhere for
+teacher-authored / OTA-pulled fragments to land:
+
+  * SYSTEM layer — read-only, ships with the app. The built-in fragments. From source this is the
+    package dir; packaged it's bundled package data (resolved via importlib.resources, which works
+    from source, a wheel, or a bundle). Moves only with a software update.
+  * USER layer — writable, ``~/.gini/content/fragments``. Teacher-authored fragments and content
+    pulled over the air from the Teaching Center. Overlays the system layer: a user fragment with the
+    same id as a built-in wins (so a course can override), but usually it just adds new ones.
+
+`ENGINE_VERSION` is the vocabulary version a fragment is authored/validated against; a fragment YAML
+stamps it so the Teaching Center and each student client can refuse-with-reason on a version gap
+rather than mis-compose. See GINI_AUTHORING_DESIGN.md.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# The engine's vocabulary version. Bump when the set of primitives (elements / predicates / probes /
+# capabilities) changes in a way that content must be re-validated against. Authored fragments stamp
+# the version they were blessed on.
+ENGINE_VERSION = "6.0"
+FRAGMENT_SCHEMA = 1               # the fragment YAML shape; bump on breaking schema changes
+
+
+def _home() -> Path:
+    # Same rule as app.paths.gini_home, replicated so `domain` stays free of an `app` import.
+    return Path(os.environ.get("GINI_HOME_DIR") or (Path.home() / ".gini")).expanduser()
+
+
+def system_content_dir() -> Path:
+    """The bundled built-in fragments — packaging-safe."""
+    try:
+        from importlib.resources import files
+        p = Path(str(files("gini.domain"))) / "missions" / "networking"
+        if p.exists():
+            return p
+    except Exception:                                    # noqa: BLE001 — fall back to __file__
+        pass
+    return Path(__file__).parent / "missions" / "networking"
+
+
+def user_content_dir() -> Path:
+    """Where authored / OTA fragments live. Created on demand (never at import)."""
+    return _home() / "content" / "fragments"
+
+
+def ensure_user_content_dir() -> Path:
+    d = user_content_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def content_dirs() -> list[Path]:
+    """System first, user second — user overlays system when ids collide."""
+    return [system_content_dir(), user_content_dir()]

gini/domain/cpu_journey.py

@@ -0,0 +1,89 @@
+"""The two ways the CPU changes what it's doing in xv6 — as ordered, steppable stages.
+
+Students constantly conflate a *system call* (a TRAP: same process, user<->kernel, saves the
+TRAPFRAME) with a *context switch* (swtch: a different process, kernel<->kernel, saves the
+CONTEXT). And a *preemption* is both, nested. This module is the pure data behind the step-driven
+"CPU journey" view: each stage says which privilege band and which process lane the CPU is in,
+and which save-area is being written/read — so the difference becomes visible one step at a time.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Stage:
+    title: str
+    band: str        # "user" | "kernel"
+    lane: str        # "A" (running proc) | "sched" | "B" (next proc)
+    save: str        # "trapframe" | "context" | ""  (which save-area this stage touches)
+    caption: str
+
+
+# A system call: one process, dips into the kernel and back. Save unit = trapframe.
+SYSCALL = [
+    Stage("ecall", "user", "A", "",
+          "The user program puts the syscall number in a7 and args in a0–a5, then executes "
+          "`ecall` — a deliberate trap into the kernel."),
+    Stage("uservec", "kernel", "A", "trapframe",
+          "Hardware jumps to uservec (trampoline). It saves ALL user registers into this "
+          "process's trapframe and switches to the kernel page table."),
+    Stage("usertrap", "kernel", "A", "",
+          "usertrap() sees scause = 8 (a syscall), advances the saved epc past the ecall, "
+          "enables interrupts, and calls syscall()."),
+    Stage("syscall()", "kernel", "A", "",
+          "syscall() reads a7, dispatches syscalls[a7] (e.g. sys_fork), and stores the result "
+          "back into the trapframe's a0."),
+    Stage("userret", "kernel", "A", "trapframe",
+          "userret restores the user registers FROM the trapframe, switches back to the user "
+          "page table, and executes sret."),
+    Stage("resume", "user", "A", "",
+          "The SAME process resumes right after its ecall, with the return value in a0. No other "
+          "process ran. Privilege went U → S → U."),
+]
+
+# A context switch: kernel thread of A hands the CPU to B via the scheduler. Save unit = context.
+CONTEXT = [
+    Stage("sched()", "kernel", "A", "",
+          "Process A's kernel thread gives up the CPU (yield or sleep) and calls sched(), which "
+          "calls swtch()."),
+    Stage("swtch → sched", "kernel", "A", "context",
+          "swtch saves A's 14 callee-saved registers into A's context and loads the scheduler's "
+          "context. The CPU is now running scheduler()."),
+    Stage("scheduler()", "kernel", "sched", "",
+          "The per-CPU scheduler loop scans proc[] and picks the next RUNNABLE process, B, and "
+          "marks it RUNNING."),
+    Stage("swtch → B", "kernel", "B", "context",
+          "swtch saves the scheduler's context and loads B's context. The CPU is now running B's "
+          "kernel thread, exactly where B last called swtch."),
+    Stage("B resumes", "kernel", "B", "",
+          "B returns up through its own kernel path. A DIFFERENT process now has the CPU. "
+          "Privilege stayed in S the whole time — no user/kernel crossing."),
+]
+
+# Preemption: a timer TRAP that triggers a context SWITCH — both mechanisms, nested.
+PREEMPT = [
+    Stage("timer trap", "kernel", "A", "trapframe",
+          "A timer interrupt traps process A into the kernel — uservec saves A's trapframe. This "
+          "is a TRAP, just like a syscall."),
+    Stage("yield()", "kernel", "A", "",
+          "usertrap sees a timer (which_dev == 2) and, once the time-slice is up, calls yield() "
+          "→ sched()."),
+    Stage("swtch → sched", "kernel", "A", "context",
+          "swtch saves A's CONTEXT and enters the scheduler — a context switch now happens INSIDE "
+          "the trap. Two different save-areas, one event."),
+    Stage("swtch → B", "kernel", "B", "context",
+          "The scheduler picks B and swtch loads B's context."),
+    Stage("userret (B)", "kernel", "B", "trapframe",
+          "B eventually returns to user via userret, restoring B's TRAPFRAME."),
+    Stage("resume B", "user", "B", "",
+          "A DIFFERENT process resumes in user mode. Preemption = a trap (trapframe) wrapping a "
+          "context switch (context)."),
+]
+
+JOURNEYS = {"syscall": SYSCALL, "context": CONTEXT, "preempt": PREEMPT}
+JOURNEY_TITLES = {
+    "syscall": "System call (trap · same process)",
+    "context": "Context switch (swtch · different process)",
+    "preempt": "Preemption (trap + context switch)",
+}