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

gini/domain/fragment_yaml.py

@@ -0,0 +1,230 @@
+"""Fragment YAML — read/write mission fragments as data (GINI_MISSIONS_COMPOSABLE_DESIGN.md §7).
+
+This is the "content is data, behaviour is code" line made concrete: a *foundational fragment* is a
+YAML file the local install ships (bound to the local oracle's predicates); the engine composes them.
+The Teaching Center distributes compositions that REFERENCE these — never new foundational fragments
+(a new primitive would need a predicate the local oracle can't run). See the loader's `validate`,
+which refuses any fragment whose predicates don't parse, whose roles are unknown, or whose element
+types aren't real — so a broken pack never reaches a student.
+"""
+from __future__ import annotations
+
+import glob
+import os
+
+import yaml
+
+from . import capabilities as _caps
+from .objectives import check_ok, unknown_element_types
+
+# `fragments` is imported lazily inside the functions below — importing this module must NOT trigger
+# the fragments load (fragments imports us back to load its YAML packs; a top-level import would cycle).
+_LAYERS = {"core", "exercise", "observe"}
+
+
+def to_dict(frag: Fragment) -> dict:
+    """A fragment → a clean dict for YAML (empty fields pruned)."""
+    d: dict = {"id": frag.id, "layer": frag.layer}
+    for k in ("teaches", "spirit", "summary", "parent", "step"):
+        v = getattr(frag, k)
+        if v:
+            d[k] = v
+    if frag.provides:
+        d["provides"] = list(frag.provides)
+    if frag.requires:
+        d["requires"] = list(frag.requires)
+    if frag.complete_when and frag.complete_when != "all":
+        d["complete_when"] = frag.complete_when
+    if frag.objectives:
+        d["objectives"] = [_obj_to_dict(o) for o in frag.objectives]
+    if frag.misconceptions:
+        d["misconceptions"] = list(frag.misconceptions)
+    if frag.peers:
+        d["peers"] = list(frag.peers)
+    if not frag.catalog:                     # standalone-mission by default; only note the exceptions
+        d["catalog"] = False
+    if frag.stage:
+        d["stage"] = frag.stage
+    if getattr(frag, "slots", ()):
+        d["slots"] = [_slot_to_dict(s) for s in frag.slots]
+    if getattr(frag, "peerings", ()):
+        d["peerings"] = [_peering_to_dict(p) for p in frag.peerings]
+    if frag.forks:
+        d["forks"] = [_fork_to_dict(f) for f in frag.forks]
+    for k in ("engine_version", "author"):   # provenance — only present on authored fragments
+        v = getattr(frag, k)
+        if v:
+            d[k] = v
+    if getattr(frag, "certified", False):    # the runtime-playtest stamp travels to the TC
+        d["certified"] = True
+    if frag.schema_version and frag.schema_version != 1:
+        d["schema_version"] = frag.schema_version
+    return d
+
+
+def _slot_to_dict(s) -> dict:
+    d = {"name": s.name, "role": s.role}
+    if s.min != 1:
+        d["min"] = s.min
+    if s.max != 1:
+        d["max"] = s.max
+    if not s.distinct:
+        d["distinct"] = False
+    return d
+
+
+def _slots_from(rows) -> tuple:
+    from .fragments import Slot
+    return tuple(Slot(name=s["name"], role=s["role"], min=int(s.get("min", 1)),
+                      max=int(s.get("max", 1)), distinct=bool(s.get("distinct", True)))
+                 for s in (rows or []))
+
+
+def _peering_to_dict(p) -> dict:
+    d = {"name": p.name, "role": p.role, "topology": p.topology}
+    if p.min != 2:
+        d["min"] = p.min
+    if p.max != 0:
+        d["max"] = p.max
+    return d
+
+
+def _peerings_from(rows) -> tuple:
+    from .fragments import Peering
+    return tuple(Peering(name=p["name"], role=p["role"], min=int(p.get("min", 2)),
+                         max=int(p.get("max", 0)), topology=p.get("topology", "mesh"))
+                 for p in (rows or []))
+
+
+def _fork_to_dict(f) -> dict:
+    d = {"id": f.id}
+    if f.label:
+        d["label"] = f.label
+    d["difficulty"] = f.difficulty
+    d["kind"] = f.kind
+    d["objectives"] = [_obj_to_dict(o) for o in f.objectives]
+    return d
+
+
+def _obj_to_dict(o: ObjectiveTemplate) -> dict:
+    d = {"id": o.id, "say": o.say, "check": o.check}
+    if o.kind and o.kind != "structural":
+        d["kind"] = o.kind
+    if o.probe:
+        d["probe"] = o.probe
+    if o.level:
+        d["level"] = o.level
+    if getattr(o, "stars", 0):
+        d["stars"] = o.stars
+    if not o.check:
+        d.pop("check")
+    return d
+
+
+def _objs_from(rows) -> tuple:
+    from .fragments import ObjectiveTemplate
+    return tuple(ObjectiveTemplate(id=o["id"], say=o.get("say", o["id"]),
+                                   kind=o.get("kind", "structural"),
+                                   check=o.get("check", ""), probe=o.get("probe", ""),
+                                   level=o.get("level"), stars=int(o.get("stars", 0) or 0))
+                 for o in (rows or []))
+
+
+def fragment_from_dict(d: dict):
+    from .fragments import CONVERGE, Fork, Fragment
+    forks = tuple(Fork(id=f["id"], label=f.get("label", ""),
+                       difficulty=int(f.get("difficulty", 1)), kind=f.get("kind", CONVERGE),
+                       objectives=_objs_from(f.get("objectives")))
+                  for f in (d.get("forks", []) or []))
+    return Fragment(
+        id=d["id"], layer=d.get("layer", "core"), teaches=d.get("teaches", ""),
+        spirit=d.get("spirit", ""), summary=d.get("summary", ""),
+        provides=tuple(d.get("provides", []) or ()), requires=tuple(d.get("requires", []) or ()),
+        objectives=_objs_from(d.get("objectives")),
+        misconceptions=tuple(d.get("misconceptions", []) or ()),
+        complete_when=d.get("complete_when", "all"), parent=d.get("parent", ""),
+        peers=tuple(d.get("peers", []) or ()), step=d.get("step", ""),
+        catalog=bool(d.get("catalog", True)), stage=dict(d.get("stage", {}) or {}),
+        slots=_slots_from(d.get("slots")), peerings=_peerings_from(d.get("peerings")),
+        forks=forks, engine_version=str(d.get("engine_version", "")),
+        schema_version=int(d.get("schema_version", 1)), author=str(d.get("author", "")),
+        certified=bool(d.get("certified", False)))
+
+
+def to_yaml(frag: Fragment) -> str:
+    return yaml.safe_dump(to_dict(frag), sort_keys=False, allow_unicode=True, width=100)
+
+
+def from_yaml(text: str) -> Fragment:
+    return fragment_from_dict(yaml.safe_load(text))
+
+
+def validate(frag: Fragment) -> list[str]:
+    """Problems that make a fragment unloadable (empty = good)."""
+    problems: list[str] = []
+    if not frag.id:
+        problems.append("fragment missing id")
+    if frag.layer not in _LAYERS:
+        problems.append(f"bad layer {frag.layer!r}")
+    bad_roles = _caps.unknown_roles(list(frag.provides) + list(frag.requires))
+    if bad_roles:
+        problems.append(f"unknown capability roles {bad_roles}")
+    from .fragments import CONVERGE, DIVERGE
+    seen: set[str] = set()
+    _validate_objectives(frag.objectives, seen, problems, "objective")
+    for fk in frag.forks:                        # forks are validated exactly like the core ladder
+        if fk.kind not in (CONVERGE, DIVERGE):
+            problems.append(f"fork {fk.id!r}: bad kind {fk.kind!r}")
+        if not fk.objectives:
+            problems.append(f"fork {fk.id!r} has no objectives")
+        _validate_objectives(fk.objectives, seen, problems, f"fork {fk.id!r} objective")
+    return problems
+
+
+def _validate_objectives(objs, seen: set, problems: list, label: str) -> None:
+    from .probes import probe_ok
+    for o in objs:
+        if o.id in seen:
+            problems.append(f"duplicate objective id {o.id!r}")
+        seen.add(o.id)
+        if o.kind == "structural" and o.check:
+            if not check_ok(o.check):
+                problems.append(f"{label} {o.id!r}: check does not parse: {o.check!r}")
+            else:
+                bad = unknown_element_types(o.check)
+                if bad:
+                    problems.append(f"{label} {o.id!r}: unknown element types {bad}")
+        elif o.kind == "behavioral":
+            if not o.probe:
+                problems.append(f"behavioral {label} {o.id!r} has no probe")
+            elif not probe_ok(o.probe):
+                problems.append(f"{label} {o.id!r}: probe does not parse: {o.probe!r}")
+
+
+def load_dir(path: str, *, strict: bool = True):
+    """Load + validate every *.yaml fragment in a directory.
+
+    Returns (fragments, warnings). `strict=True` (the system layer) raises on the first invalid pack —
+    a broken built-in is a bug. `strict=False` (the user / OTA layer) DECLINES a bad pack and keeps
+    going, collecting a warning — a broken authored/pulled fragment must never brick the client.
+    """
+    out: dict[str, Fragment] = {}
+    warnings: list[str] = []
+    if not os.path.isdir(path):
+        return out, warnings
+    for fp in sorted(glob.glob(os.path.join(path, "*.yaml"))):
+        name = os.path.basename(fp)
+        try:
+            frag = fragment_from_dict(yaml.safe_load(open(fp, encoding="utf-8").read()))
+            problems = validate(frag)
+        except Exception as e:                   # noqa: BLE001 — malformed YAML is just "declined"
+            problems = [f"could not read: {e}"]
+            frag = None
+        if problems:
+            msg = f"{name}: {'; '.join(problems)}"
+            if strict:
+                raise ValueError(msg)
+            warnings.append(msg)                 # refuse this one, keep the rest
+            continue
+        out[frag.id] = frag
+    return out, warnings

gini/domain/fragments.py

@@ -0,0 +1,169 @@
+"""Mission fragments — the composable building blocks.
+
+A *fragment* is smaller than a whole mission: a labelled piece (core / exercise / observe) that
+declares a capability contract (`provides` / `requires`) so the assembler can join fragments into a
+complete mission by graph closure. The 12 seed Game-Catalog archetypes are re-exposed here as
+`core` fragments (with capability metadata attached — the catalog stays the source of their
+objectives, so nothing regresses), plus a handful of *enrichment* fragments (the exercise/observe
+layers) that make a bare skeleton educational.
+
+See GINI_MISSIONS_COMPOSABLE_DESIGN.md §3–4. Pure data; no Qt, no LLM.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .content import content_dirs
+from .objectives import Objective
+
+CORE, EXERCISE, OBSERVE = "core", "exercise", "observe"
+
+# fork kinds — see GINI_AUTHORING_DESIGN.md "FORKS — the difficulty knob"
+CONVERGE, DIVERGE = "converge", "diverge"
+
+
+@dataclass(frozen=True)
+class ObjectiveTemplate:
+    id: str
+    say: str
+    kind: str = "structural"     # structural | behavioral
+    check: str = ""              # structural predicate (may contain {ref} placeholders)
+    probe: str = ""              # behavioral probe (may contain {ref} placeholders)
+    level: int | None = None     # explicit ladder tier (1 place · 2 connect · 3 group · 4 live)
+    stars: int = 0               # difficulty PASS: 0 = base, 1+ = harder progressive passes
+
+
+@dataclass(frozen=True)
+class Slot:
+    """A named, typed dependency socket — the composition non-terminal (see the graph-grammar model).
+    `role` is the capability it needs (is-a matched, so a `network` slot accepts a LAN or a routed
+    network). Cardinality `min..max` (max 0 = unbounded) makes it a fixed leg or a variable group
+    (a router's ≥2 legs, a load balancer's N backends). `distinct` = must bind to a different
+    provider than the fragment's other slots. Objectives reference a slot as `type@name`."""
+    name: str
+    role: str
+    min: int = 1
+    max: int = 1
+    distinct: bool = True
+
+
+@dataclass(frozen=True)
+class Peering:
+    """A LATERAL composition group — N sibling members of one role that interconnect as PEERS (a
+    graph, possibly with cycles), unlike a Slot which links the delta to each member. `topology`
+    shapes the graph: `mesh` (every pair), `ring`, `line`, or `star` (member 0 is the hub). This is
+    the axis slots can't express — meshes/graphs of routers. Objectives reference it as `type@name`
+    (all-pairs), and the assembler wires the members' connection points per topology."""
+    name: str
+    role: str
+    min: int = 2
+    max: int = 0                            # 0 = unbounded
+    topology: str = "mesh"                  # mesh | ring | line | star
+
+
+@dataclass(frozen=True)
+class Fork:
+    """A difficulty branch off the core. `converge` = a harder *way to the same goal* (rejoins the
+    main line); `diverge` = a *different path* (may not rejoin). Completing a fork lifts the band
+    toward gold — difficulty is how deep into the forks you go."""
+    id: str
+    label: str = ""
+    difficulty: int = 1                     # 1 = the golden path; higher = harder
+    kind: str = CONVERGE                    # converge | diverge
+    objectives: tuple[ObjectiveTemplate, ...] = ()
+
+    def instantiate(self) -> list[Objective]:
+        return [Objective(id=t.id, say=t.say, kind=t.kind, check=t.check, probe=t.probe,
+                          level=t.level, stars=getattr(t, "stars", 0)) for t in self.objectives]
+
+
+@dataclass(frozen=True)
+class Fragment:
+    id: str
+    layer: str                              # core | exercise | observe
+    teaches: str = ""                       # concepts.Concept.key
+    spirit: str = ""                        # mechanism-free success description (game master reasons on it)
+    summary: str = ""
+    provides: tuple[str, ...] = ()
+    requires: tuple[str, ...] = ()
+    objectives: tuple[ObjectiveTemplate, ...] = ()
+    misconceptions: tuple[str, ...] = ()
+    complete_when: str = "all"
+    parent: str = ""                        # domain-taxonomy node (browsing / coarse selection)
+    peers: tuple[str, ...] = ()             # horizontal "goes-with" hints
+    step: str = ""                          # optional guided beat this fragment contributes
+    catalog: bool = True                    # a standalone, pickable mission? (False = pure layer)
+    stage: dict = field(default_factory=dict)   # optional pre-built board (M3 staging)
+    slots: tuple[Slot, ...] = ()           # named dependency sockets (the composition non-terminals)
+    peerings: tuple[Peering, ...] = ()     # lateral peer groups (meshes/graphs — the Phase 5 axis)
+    forks: tuple[Fork, ...] = ()            # optional difficulty branches (the golden-path model)
+    # provenance / compatibility — stamped when a fragment is authored & blessed. Empty on built-ins
+    # (they ARE the engine). Lets the TC / a student client refuse-with-reason on a version gap.
+    engine_version: str = ""
+    schema_version: int = 1
+    author: str = ""
+    certified: bool = False                 # runtime-playtested at the client (winnable + live)
+
+    def instantiate(self) -> list[Objective]:
+        return [Objective(id=t.id, say=t.say, kind=t.kind, check=t.check, probe=t.probe,
+                          level=t.level, stars=getattr(t, "stars", 0)) for t in self.objectives]
+
+
+# -- registry: fragments loaded from the SYSTEM layer + the USER layer -------- #
+# Content is data (YAML), behaviour is code. The system layer (bundled built-ins) is authoritative and
+# must be valid — a broken built-in is a bug and raises. The user layer (~/.gini/content/fragments:
+# authored + OTA-pulled) is best-effort — a broken pack there is DECLINED, not fatal, so a bad OTA
+# fragment can never brick a student's client. User fragments overlay system ones by id.
+LOAD_WARNINGS: list[str] = []
+
+
+def _load() -> dict[str, Fragment]:
+    from . import content as _content
+    from . import fragment_yaml as _fy          # deferred: fragment_yaml imports names from here
+    LOAD_WARNINGS.clear()
+    roots = _content.content_dirs()
+    out: dict[str, Fragment] = {}
+    for i, root in enumerate(roots):
+        strict = (i == 0)                        # system layer strict; user layer best-effort
+        loaded, warnings = _fy.load_dir(str(root), strict=strict)
+        out.update(loaded)                       # later roots (user) overlay earlier (system)
+        LOAD_WARNINGS.extend(warnings)
+    return out
+
+
+FRAGMENTS: dict[str, Fragment] = _load()
+
+
+def reload() -> None:
+    """Re-read the YAML packs from disk (for authoring / hot-edit / after an OTA pull)."""
+    global FRAGMENTS
+    FRAGMENTS = _load()
+
+
+def get(fragment_id: str) -> Fragment | None:
+    return FRAGMENTS.get(fragment_id)
+
+
+def all_fragments() -> list[Fragment]:
+    return list(FRAGMENTS.values())
+
+
+def cores() -> list[Fragment]:
+    return [f for f in FRAGMENTS.values() if f.layer == CORE]
+
+
+def by_layer(layer: str) -> list[Fragment]:
+    return [f for f in FRAGMENTS.values() if f.layer == layer]
+
+
+def provides_role(fragment: Fragment, required: str) -> bool:
+    from . import capabilities as _caps
+    return _caps.any_satisfies(fragment.provides, required)
+
+
+def find_providers(required: str, *, layer: str | None = None) -> list[Fragment]:
+    """Fragments that provide (satisfy) the `required` role, optionally restricted to a layer."""
+    out = [f for f in FRAGMENTS.values() if provides_role(f, required)]
+    if layer is not None:
+        out = [f for f in out if f.layer == layer]
+    return out

gini/domain/games/__init__.py

@@ -0,0 +1,2 @@
+"""Diagnose-game case sources — one module per game, each turning real telemetry into labeled
+Cases for the shared engine in domain/diagnose.py."""

gini/domain/games/paging_games.py

@@ -0,0 +1,119 @@
+"""Three more paging games on the page-replacement simulator — all with EXACT ground truth computed
+by the simulator (no guessing on our side):
+
+  fault-count  (estimate)        — refs + frames + policy → how many faults?
+  belady       (predict-outcome) — will adding ONE frame reduce FIFO's faults? (sometimes NO — the
+                                    anomaly)
+  showdown     (classify)        — on this string, does FIFO or LRU fault fewer (or tie)?
+"""
+from __future__ import annotations
+
+from ..diagnose import Case, GameSpec
+from ..paging_sim import resident_state, simulate
+
+# a small bank of reference strings (kept short enough to reason about by hand)
+_STRINGS = [
+    ([1, 2, 3, 4, 1, 2, 5, 1, 2, 3, 4, 5], 3),          # the classic Belady string
+    ([7, 0, 1, 2, 0, 3, 0, 4, 2, 3, 0, 3, 2], 3),
+    ([0, 1, 2, 0, 1, 2, 0, 1, 2, 0], 2),
+    ([1, 2, 3, 1, 4, 1, 5, 6, 2, 1], 3),
+    ([4, 3, 2, 1, 4, 3, 5, 4, 3, 2, 1, 5], 4),
+    ([1, 2, 1, 3, 1, 4, 1, 5, 1, 6], 3),
+]
+
+# ---- fault-count (estimate) ----------------------------------------------- #
+FAULTCOUNT_SPEC = GameSpec("faults-estimate", "Count the page faults",
+                           "How many page faults will this run take?", classes=[],
+                           answer="estimate", tolerance=2, unit="faults")
+
+
+def faultcount_cases() -> list:
+    out = []
+    for i, (refs, frames) in enumerate(_STRINGS):
+        faults = simulate(refs, frames, "lru").faults
+        out.append(Case(f"fc-{i}", {"refs": refs, "frames": frames, "policy": "LRU"},
+                        faults, subtitle=f"{faults} faults"))
+    return out
+
+
+# ---- Belady spotter (predict-outcome) ------------------------------------- #
+BELADY_CLASSES = ["fewer faults", "same or more"]
+BELADY_SPEC = GameSpec("belady-spot", "Belady spotter",
+                       "Will adding ONE more frame reduce FIFO's faults?",
+                       BELADY_CLASSES, {"fewer faults": "fewer", "same or more": "same+"})
+
+
+def belady_cases() -> list:
+    out = []
+    for i, (refs, frames) in enumerate(_STRINGS):
+        f0 = simulate(refs, frames, "fifo").faults
+        f1 = simulate(refs, frames + 1, "fifo").faults
+        truth = "fewer faults" if f1 < f0 else "same or more"
+        out.append(Case(f"bel-{i}",
+                        {"refs": refs, "frames": frames, "policy": "FIFO",
+                         "note": f"currently {f0} faults with {frames} frames — add one?"},
+                        truth, subtitle=f"{frames}f: {f0}  →  {frames + 1}f: {f1}"))
+    return out
+
+
+# ---- policy showdown (classify) ------------------------------------------- #
+SHOWDOWN_CLASSES = ["FIFO", "LRU", "tie"]
+SHOWDOWN_SPEC = GameSpec("policy-showdown", "Policy showdown",
+                         "Which faults fewer on this string — FIFO or LRU?",
+                         SHOWDOWN_CLASSES, {"FIFO": "FIFO", "LRU": "LRU", "tie": "tie"})
+
+
+def showdown_cases() -> list:
+    out = []
+    for i, (refs, frames) in enumerate(_STRINGS):
+        fifo = simulate(refs, frames, "fifo").faults
+        lru = simulate(refs, frames, "lru").faults
+        truth = "FIFO" if fifo < lru else "LRU" if lru < fifo else "tie"
+        out.append(Case(f"sd-{i}", {"refs": refs, "frames": frames},
+                        truth, subtitle=f"FIFO {fifo}  ·  LRU {lru}"))
+    return out
+
+
+# ---- next eviction (spot the culprit) ------------------------------------- #
+NEXTEVICT_SPEC = GameSpec("next-evict", "Spot the next eviction",
+                          "Which resident page is evicted on the next fault?",
+                          classes=[], answer="spot")
+
+
+def nextevict_cases() -> list:
+    out = []
+    for i, (refs, frames) in enumerate(_STRINGS):
+        for policy in ("fifo", "lru"):
+            resident, order = resident_state(refs, frames, policy)
+            if len(resident) < frames or not order:
+                continue
+            miss = [p for p in sorted(set(refs)) if p not in resident]
+            if not miss:
+                continue
+            victim = order[0]
+            out.append(Case(
+                f"ne-{i}-{policy}",
+                {"refs": refs, "frames": frames, "policy": policy.upper(),
+                 "note": f"next access: page {miss[0]} (faults) — who is evicted?"},
+                victim, subtitle=f"evict page {victim}", options=sorted(resident)))
+    return out
+
+
+# ---- policy rank (order them) --------------------------------------------- #
+POLICYRANK_SPEC = GameSpec("policy-rank", "Rank the policies",
+                           "Order FIFO, LRU, OPT by faults — fewest first.",
+                           classes=[], answer="rank")
+
+
+def policyrank_cases() -> list:
+    out = []
+    for i, (refs, frames) in enumerate(_STRINGS):
+        counts = {pol: simulate(refs, frames, pol).faults for pol in ("fifo", "lru", "opt")}
+        if len(set(counts.values())) < 3:              # only strictly-ordered strings (no ties)
+            continue
+        order = sorted(counts, key=lambda p: counts[p])
+        out.append(Case(f"pr-{i}", {"refs": refs, "frames": frames},
+                        [p.upper() for p in order],
+                        subtitle="  <  ".join(f"{p.upper()} {counts[p]}" for p in order),
+                        options=["FIFO", "LRU", "OPT"]))
+    return out

gini/domain/games/policy_game.py

@@ -0,0 +1,86 @@
+"""Case source for the guess-the-scheduler-policy game.
+
+The signature is a short running-pid timeline (a Gantt window); the truth is the scheduler that
+produced it. Live cases come from the real `SchedTimeline` + the kernel's actual `sched_policy`; the
+demo deck synthesizes the three characteristic patterns:
+
+  round-robin — a strict cyclic rotation through the runnable set
+  priority    — one process dominates (highest priority runs, others starve)
+  lottery     — no pattern (a random draw)
+"""
+from __future__ import annotations
+
+import random
+from collections import Counter
+
+from ..diagnose import Case, GameSpec
+
+POLICY_CLASSES = ["round-robin", "priority", "lottery"]
+POLICY_ABBR = {"round-robin": "RR", "priority": "prio", "lottery": "lotto"}
+
+POLICY_SPEC = GameSpec(
+    id="guess-policy",
+    title="Guess the scheduler",
+    prompt="Which scheduler produced this timeline?",
+    classes=POLICY_CLASSES,
+    abbrev=POLICY_ABBR,
+)
+
+
+def _rr(pids, n) -> list:
+    return [pids[i % len(pids)] for i in range(n)]
+
+
+def _priority(pids, n, rng) -> list:
+    """One pid dominates; every so often another sneaks a slice (aging), then back."""
+    top = pids[0]
+    out = []
+    for _ in range(n):
+        out.append(rng.choice(pids[1:]) if pids[1:] and rng.random() < 0.12 else top)
+    return out
+
+
+def _lottery(pids, n, rng) -> list:
+    return [rng.choice(pids) for _ in range(n)]
+
+
+def _is_periodic(pids, period) -> bool:
+    if period <= 0 or len(pids) <= period:
+        return False
+    return all(pids[i] == pids[i - period] for i in range(period, len(pids)))
+
+
+def classify_timeline(pids) -> str:
+    """A rough heuristic used for the practice-mode HINT (not the grader). Dominant → priority;
+    strictly periodic over the distinct set → round-robin; otherwise lottery."""
+    if not pids:
+        return "lottery"
+    c = Counter(pids)
+    if c.most_common(1)[0][1] / len(pids) > 0.55:
+        return "priority"
+    if _is_periodic(pids, len(set(pids))):
+        return "round-robin"
+    return "lottery"
+
+
+def demo_cases(seed: int = 0, n: int = 24, instances: int = 2) -> list:
+    """The offline deck: `instances` timelines per policy."""
+    rng = random.Random(seed)
+    pids = [3, 4, 5]
+    out = []
+    for k in range(instances):
+        rr = _rr(pids, n)
+        out.append(Case(f"rr{k}", rr, "round-robin", "round-robin", classify_timeline(rr)))
+        pr = _priority(pids, n, rng)
+        out.append(Case(f"prio{k}", pr, "priority", "priority", classify_timeline(pr)))
+        lo = _lottery(pids, n, rng)
+        out.append(Case(f"lot{k}", lo, "lottery", "lottery", classify_timeline(lo)))
+    return out
+
+
+def live_cases(timeline_pids, policy_name) -> list:
+    """One case from the live Gantt window + the kernel's real policy (empty if we lack either)."""
+    pids = [p for p in (timeline_pids or []) if p is not None]
+    if len(pids) < 6 or not policy_name:
+        return []
+    return [Case("live", pids[-24:], policy_name, policy_name, classify_timeline(pids[-24:]))]

gini/domain/games/process_game.py

@@ -0,0 +1,48 @@
+"""Case source for the process-classify game (instance #1 of the Diagnose engine).
+
+Reuses the fingerprint domain: a Case's signature is the 5-axis fingerprint, its truth is the
+oracle's GROUND_TRUTH class for the launched program, and its hint is the rule-classifier's own guess
+(shown in practice mode)."""
+from __future__ import annotations
+
+from ..diagnose import GameSpec
+from ..diagnose import Case
+from ..fingerprint import CLASSES, classify, demo_features, fingerprint, true_class
+
+PROCESS_ABBR = {"cpu-bound": "cpu", "io-bound": "io", "memory": "mem",
+                "fork-heavy": "fork", "mixed": "mix"}
+
+PROCESS_SPEC = GameSpec(
+    id="process-classify",
+    title="Classify the process",
+    prompt="What is this process?",
+    classes=CLASSES,
+    abbrev=PROCESS_ABBR,
+)
+
+
+def _case(name: str, fp: dict, cid: str) -> Case | None:
+    t = true_class(name)
+    if not t:
+        return None
+    return Case(id=cid, signature=fp, truth=t, subtitle=name, hint=classify(fp))
+
+
+def demo_cases() -> list:
+    """Canned deck from the shipped programs — always available (offline fallback)."""
+    out = []
+    for f in demo_features():
+        c = _case(f.name, fingerprint(f), f"proc-{f.name}")
+        if c is not None:
+            out.append(c)
+    return out
+
+
+def live_cases(fingerprints_by_pid: dict, names: dict) -> list:
+    """Cases from live fingerprints ({pid: fp}) whose program has a known ground-truth class."""
+    out = []
+    for pid, fp in fingerprints_by_pid.items():
+        c = _case(names.get(pid, ""), fp, f"proc-{pid}")
+        if c is not None:
+            out.append(c)
+    return out