tensorcode 0.1.0a1__py3-none-any.whl

tensorcode/learning/induce.py

@@ -0,0 +1,304 @@
+"""Inducing readable artifacts: decision lists, preconditions, and role types.
+
+Three inducers, each with the discipline its source repo learned the hard way:
+
+* :func:`decision_list` — greedy separate-and-conquer with an **MDL stop**, so a
+  rule has to save more bits than it costs to state. (The algorithm is
+  ``symbolic-ai-models``'s ``models/ruleinduce_001/dlist.py``, re-expressed over
+  claims instead of that repo's graph facts.)
+* :func:`preconditions` — the most-specific cover of the states in which an action
+  fired, with optional **interventional pruning**: keep a condition only if
+  removing it changes what the world does. (``synthEX``'s
+  ``perception/induce_rules.py`` reports precision 0.44 → 0.74 from exactly this.)
+* :func:`role_type` — the least general type covering every observed filler, with a
+  **productivity gate**: a shape generalises only when many distinct fillers share
+  it and almost all of them are of that kind, otherwise the forms are memorised.
+  (``symbolic-ai-models``'s ``reader/learned.py`` ``Lexicon.induce``.)
+
+Nothing here adopts what it induces. Adoption is :mod:`tensorcode.learning.verify`,
+which is where the controls live.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Callable, Hashable, Iterable, Mapping, Sequence
+
+from ..outcomes import Score, Unknown
+from .literals import Case, Literal
+
+# ------------------------------------------------------------- decision lists
+
+
+@dataclass
+class Rule:
+    conditions: tuple[Literal, ...]
+    label: Any
+    support: int = 0
+    correct: int = 0
+
+    def matches(self, facts: Any) -> bool:
+        return all(c.holds(facts) for c in self.conditions)
+
+    @property
+    def confidence(self) -> float:
+        return self.correct / max(1, self.support)
+
+    def cost(self) -> int:
+        return 2 + sum(c.cost() for c in self.conditions)
+
+    def __repr__(self) -> str:
+        body = " ∧ ".join(repr(c) for c in self.conditions) or "true"
+        return f"IF {body} THEN {self.label!r}  [{self.correct}/{self.support}]"
+
+
+@dataclass
+class DecisionList:
+    """An ordered list of rules you can read, argue with, and price."""
+
+    rules: list[Rule] = field(default_factory=list)
+    default: Any = None
+    considered: int = 0
+
+    def predict(self, facts: Any) -> Any:
+        for rule in self.rules:
+            if rule.matches(facts):
+                return rule.label
+        return self.default
+
+    def explain(self, facts: Any) -> tuple[Any, Rule | None]:
+        for rule in self.rules:
+            if rule.matches(facts):
+                return rule.label, rule
+        return self.default, None
+
+    def decide(self, facts: Any) -> tuple[Any, "Rule | None", Any]:
+        """Predict, and return the certificate of what the decision actually read.
+
+        The read set includes predicates that were *absent*, so an answer is
+        invalidated by a fact appearing as well as by one changing.
+        """
+        from .certificate import Reader
+
+        reader = Reader(dict(facts) if isinstance(facts, frozenset) else facts, note="decision_list")
+        label, rule = self.explain(reader)
+        return label, rule, reader.readset()
+
+    def score(self, facts: Any) -> Score:
+        _, rule = self.explain(facts)
+        return Score(rule.confidence if rule else 0.0, "uncalibrated")
+
+    def cost(self) -> int:
+        return sum(r.cost() for r in self.rules) + 2
+
+    def accuracy(self, cases: Sequence[Case]) -> float:
+        if not cases:
+            return 0.0
+        return sum(self.predict(facts) == label for facts, label in cases) / len(cases)
+
+    def __repr__(self) -> str:
+        return "\n".join([*(repr(r) for r in self.rules), f"ELSE {self.default!r}"])
+
+
+def _entropy(counts: Counter) -> float:
+    total = sum(counts.values())
+    if not total:
+        return 0.0
+    return -sum((c / total) * math.log2(c / total) for c in counts.values() if c)
+
+
+def decision_list(cases: Sequence[Case], literals: Sequence[Literal], *, max_conditions: int = 3,
+                  min_support: int = 2, min_confidence: float = 0.6, max_rules: int = 40,
+                  beam: int = 4, mdl: bool = True) -> DecisionList:
+    """Induce an ordered rule list. Discrete throughout: no gradients, five knobs."""
+    remaining = list(cases)
+    out = DecisionList(considered=len(literals))
+    labels = Counter(label for _, label in cases)
+    out.default = labels.most_common(1)[0][0] if labels else None
+
+    while remaining and len(out.rules) < max_rules:
+        rule = _grow(remaining, literals, max_conditions=max_conditions, min_support=min_support, beam=beam)
+        if rule is None or rule.confidence < min_confidence:
+            break
+        if mdl:
+            covered = [(f, y) for f, y in remaining if rule.matches(f)]
+            before = _entropy(Counter(y for _, y in remaining)) * len(covered)
+            after = _entropy(Counter(y for _, y in covered)) * len(covered)
+            if before - after < rule.cost():  # the rule must pay for its own statement
+                break
+        out.rules.append(rule)
+        remaining = [(f, y) for f, y in remaining if not rule.matches(f)]
+    if remaining:
+        out.default = Counter(y for _, y in remaining).most_common(1)[0][0]
+    return out
+
+
+def _grow(cases: Sequence[Case], literals: Sequence[Literal], *, max_conditions: int, min_support: int,
+          beam: int) -> Rule | None:
+    """Beam search over conjunctions, scored by information gain weighted by purity."""
+    hits = {literal: [literal.holds(facts) for facts, _ in cases] for literal in literals}
+    labels = [label for _, label in cases]
+    base = _entropy(Counter(labels))
+    n = len(cases)
+
+    def score(mask: Sequence[bool]) -> tuple[float, Counter, int]:
+        picked = [i for i, m in enumerate(mask) if m]
+        if len(picked) < min_support:
+            return -1e9, Counter(), 0
+        counts = Counter(labels[i] for i in picked)
+        return (base - _entropy(counts)) * (len(picked) / n), counts, len(picked)
+
+    beams: list[tuple[float, tuple[Literal, ...], list[bool]]] = [(0.0, (), [True] * n)]
+    best: tuple[float, tuple[Literal, ...], Counter, int] | None = None
+    for _ in range(max_conditions):
+        nxt: list[tuple[float, tuple[Literal, ...], list[bool]]] = []
+        for _, conditions, mask in beams:
+            for literal in literals:
+                if literal in conditions:
+                    continue
+                merged = [a and b for a, b in zip(mask, hits[literal])]
+                gain, counts, support = score(merged)
+                if gain <= 0:
+                    continue
+                adjusted = gain * (max(counts.values()) / max(1, support))
+                nxt.append((adjusted, conditions + (literal,), merged))
+                if best is None or adjusted > best[0]:
+                    best = (adjusted, conditions + (literal,), counts, support)
+        if not nxt:
+            break
+        nxt.sort(key=lambda row: (-row[0], tuple(repr(c) for c in row[1])))
+        beams = nxt[:beam]
+    if best is None:
+        return None
+    _, conditions, counts, support = best
+    label, correct = counts.most_common(1)[0]
+    return Rule(conditions, label, support, correct)
+
+
+# ---------------------------------------------------------------- preconditions
+
+
+@dataclass(frozen=True)
+class Precondition:
+    """What has to hold for an action to fire, and how it was established."""
+
+    action: str
+    conditions: tuple[Literal, ...]
+    support: int
+    method: str = "most-specific-cover"
+
+    def holds(self, facts: Any) -> bool:
+        return all(c.holds(facts) for c in self.conditions)
+
+    def __repr__(self) -> str:
+        body = " ∧ ".join(repr(c) for c in self.conditions) or "true"
+        return f"{self.action} needs {body}  [{self.support} firings, {self.method}]"
+
+
+def preconditions(action: str, fired: Sequence[frozenset], *,
+                  intervene: Callable[[str, frozenset], bool] | None = None,
+                  did_not_fire: Sequence[frozenset] = ()) -> Precondition:
+    """Conditions true in **every** state where the action fired.
+
+    The passive cover over-specialises: anything the world happened to keep constant
+    becomes a condition. Two optional correctives, in the order they should be tried:
+
+    * ``did_not_fire`` states drop conditions that also held when nothing happened;
+    * ``intervene(action, facts)`` is asked whether the action still fires with a
+      condition removed, which is the only way to tell a cause from a coincidence.
+    """
+    if not fired:
+        return Precondition(action, (), 0, "no firings")
+    common = set(fired[0])
+    for state in fired[1:]:
+        common &= set(state)
+    conditions = [Literal(p, v) for p, v in sorted(common, key=repr)]
+
+    if did_not_fire:
+        conditions = [c for c in conditions if not all(c.holds(state) for state in did_not_fire)]
+    method = "most-specific-cover" + ("+negatives" if did_not_fire else "")
+
+    if intervene is not None:
+        kept: list[Literal] = []
+        for condition in conditions:
+            weakened = [c for c in conditions if c is not condition]
+            probe = frozenset((c.predicate, c.value) for c in weakened)
+            if not intervene(action, probe):  # removing it stopped the action: it matters
+                kept.append(condition)
+        conditions, method = kept, method + "+intervention"
+    return Precondition(action, tuple(conditions), len(fired), method)
+
+
+def effects(before: Sequence[frozenset], after: Sequence[frozenset]) -> tuple[Literal, ...]:
+    """What every firing added: the union of new facts, kept only where it is unanimous."""
+    added: list[set] = [set(b) ^ (set(a) & set(b)) for a, b in zip(after, before)]
+    gained = [set(a) - set(b) for a, b in zip(after, before)]
+    if not gained:
+        return ()
+    common = set(gained[0])
+    for facts in gained[1:]:
+        common &= facts
+    _ = added
+    return tuple(Literal(p, v) for p, v in sorted(common, key=repr))
+
+
+# ------------------------------------------------------------------ role types
+
+
+@dataclass(frozen=True)
+class RoleType:
+    """What fills a role: a generalising shape, or a memorised set of forms."""
+
+    role: str
+    concept: str | None
+    shapes: frozenset[str] = frozenset()
+    forms: frozenset[str] = frozenset()
+    productive: bool = False
+    support: int = 0
+
+    def admits(self, value: Any) -> bool:
+        text = value if isinstance(value, str) else str(value)
+        return text in self.forms or (self.productive and shape(text) in self.shapes)
+
+    def __repr__(self) -> str:
+        how = f"shape {sorted(self.shapes)}" if self.productive else f"{len(self.forms)} memorised forms"
+        return f"{self.role}: {self.concept or 'unknown'} ({how}, {self.support} observations)"
+
+
+def shape(text: str) -> str:
+    """A token's shape: letters, digits and punctuation classes, run-length collapsed."""
+    out = []
+    for ch in text:
+        kind = "X" if ch.isupper() else "x" if ch.islower() else "9" if ch.isdigit() else ch
+        if not out or out[-1] != kind:
+            out.append(kind)
+    return "".join(out)
+
+
+def role_type(role: str, fillers: Sequence[Any], *, subsumes: Callable[[Any], str] | None = None,
+              min_forms: int = 5, purity: float = 0.9, others: Sequence[Any] = ()) -> RoleType:
+    """The least general type covering every filler, generalised only if productive.
+
+    ``subsumes`` maps a filler to its concept; the induced concept is the most
+    specific one covering all fillers. A *shape* is trusted only when it covers
+    ``min_forms`` distinct fillers and almost nothing else in ``others``, so
+    ``region_0`` generalises to ``region_84`` while ``group`` must be memorised.
+    """
+    texts = [f if isinstance(f, str) else str(f) for f in fillers]
+    concepts = {subsumes(f) for f in fillers} if subsumes else set()
+    concept = concepts.pop() if len(concepts) == 1 else None
+    by_shape: dict[str, set[str]] = defaultdict(set)
+    for text in texts:
+        by_shape[shape(text)].add(text)
+    foreign: dict[str, set[str]] = defaultdict(set)
+    for other in others:
+        text = other if isinstance(other, str) else str(other)
+        foreign[shape(text)].add(text)
+    productive = {
+        s for s, forms in by_shape.items()
+        if len(forms) >= min_forms and len(forms) >= purity * (len(forms) + len(foreign.get(s, ())))
+    }
+    memorised = {t for t in texts if shape(t) not in productive}
+    return RoleType(role, concept, frozenset(productive), frozenset(memorised), bool(productive), len(texts))

tensorcode/learning/library.py

@@ -0,0 +1,217 @@
+"""A persistent, versioned library of learned artifacts.
+
+Learning that does not outlive the process is not learning, so artifacts go to a
+directory of plain JSON: a manifest, one content-addressed file per artifact, and
+one recorded fixture per artifact. The design is
+``typed-crystallization-networks``'s ``tcn/library.py``, kept because its rules are
+the ones that stop a library quietly rotting:
+
+* **content addressing** — two names that induce the same artifact share one file,
+  so a definition is stored and charged once;
+* **versions** — publishing under an existing name allocates the next version and
+  marks every artifact that depends on the superseded digest ``stale``;
+* **fixtures** — an artifact records cases it got right, and loading replays them.
+  A disagreement raises rather than loading;
+* **provenance** — what it was induced from, by what method, when, and under which
+  verification. Nothing enters without it.
+
+There is deliberately no "load anyway" policy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterable, Mapping, Sequence
+
+from .induce import DecisionList, Rule
+from .literals import Literal
+
+
+class LibraryError(Exception):
+    pass
+
+
+class FixtureMismatch(LibraryError):
+    """A stored artifact no longer reproduces its recorded cases."""
+
+
+class MissingArtifact(LibraryError):
+    pass
+
+
+def digest_of(payload: Any) -> str:
+    return hashlib.sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class Entry:
+    name: str
+    version: int
+    digest: str
+    kind: str
+    provenance: Mapping[str, Any]
+    depends_on: tuple[str, ...] = ()
+    stale: bool = False
+    at: float = field(default_factory=time.time)
+
+    @property
+    def reference(self) -> str:
+        return f"{self.name}@{self.version}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "version": self.version, "digest": self.digest, "kind": self.kind,
+                "provenance": dict(self.provenance), "depends_on": list(self.depends_on), "stale": self.stale,
+                "at": self.at}
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Entry":
+        return cls(data["name"], data["version"], data["digest"], data["kind"], data.get("provenance", {}),
+                   tuple(data.get("depends_on", ())), bool(data.get("stale")), data.get("at", 0.0))
+
+
+# --------------------------------------------------------------- serialisation
+
+
+def _literal_to_json(literal: Literal) -> dict[str, Any]:
+    return {"predicate": literal.predicate, "value": literal.value, "negated": literal.negated, "kind": literal.kind}
+
+
+def _literal_from_json(data: Mapping[str, Any]) -> Literal:
+    return Literal(data["predicate"], data.get("value"), bool(data.get("negated")), data.get("kind", "equals"))
+
+
+def to_json(artifact: Any) -> dict[str, Any]:
+    """Artifacts are data: a reader needs this module's *format*, not its code."""
+    if isinstance(artifact, DecisionList):
+        return {"kind": "decision_list", "default": artifact.default, "considered": artifact.considered,
+                "rules": [{"conditions": [_literal_to_json(c) for c in r.conditions], "label": r.label,
+                           "support": r.support, "correct": r.correct} for r in artifact.rules]}
+    raise LibraryError(f"cannot store {type(artifact).__name__}")
+
+
+def from_json(data: Mapping[str, Any]) -> Any:
+    if data.get("kind") == "decision_list":
+        rules = [Rule(tuple(_literal_from_json(c) for c in r["conditions"]), r["label"], r.get("support", 0), r.get("correct", 0))
+                 for r in data.get("rules", ())]
+        return DecisionList(rules, data.get("default"), data.get("considered", 0))
+    raise LibraryError(f"unknown stored kind {data.get('kind')!r}")
+
+
+# -------------------------------------------------------------------- library
+
+
+class Library:
+    """A directory of learned artifacts, versioned and replayable."""
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        (self.root / "artifacts").mkdir(exist_ok=True)
+        (self.root / "fixtures").mkdir(exist_ok=True)
+        self.manifest_path = self.root / "manifest.json"
+        self.entries: list[Entry] = []
+        if self.manifest_path.exists():
+            self.entries = [Entry.from_dict(row) for row in json.loads(self.manifest_path.read_text())]
+
+    # -- reading
+    def names(self) -> list[str]:
+        return sorted({e.name for e in self.entries})
+
+    def versions(self, name: str) -> list[Entry]:
+        return [e for e in self.entries if e.name == name]
+
+    def head(self, name: str) -> Entry:
+        found = self.versions(name)
+        if not found:
+            raise MissingArtifact(name)
+        return found[-1]
+
+    def entry(self, reference: str) -> Entry:
+        if "@" not in reference:
+            return self.head(reference)
+        name, _, version = reference.partition("@")
+        for candidate in self.versions(name):
+            if candidate.version == int(version):
+                return candidate
+        raise MissingArtifact(reference)
+
+    def dependents(self, digest: str) -> list[Entry]:
+        return [e for e in self.entries if digest in e.depends_on]
+
+    # -- writing
+    def publish(self, name: str, artifact: Any, *, provenance: Mapping[str, Any],
+                fixture: Sequence[tuple[Any, Any]] = (), depends_on: Sequence[str] = ()) -> Entry:
+        """Store an artifact as the next version of ``name``, with a replayable fixture."""
+        payload = to_json(artifact)
+        digest = digest_of(payload)
+        (self.root / "artifacts" / f"{digest}.json").write_text(json.dumps(payload, indent=1, default=str))
+        (self.root / "fixtures" / f"{digest}.json").write_text(
+            json.dumps([{"facts": sorted(((p, v) for p, v in facts), key=repr), "expect": expect}
+                        for facts, expect in fixture], indent=1, default=str))
+        superseded = self.versions(name)
+        version = superseded[-1].version + 1 if superseded else 1
+        entry = Entry(name, version, digest, payload["kind"], dict(provenance), tuple(depends_on))
+        # relearning marks every dependent stale: it must be revalidated, not trusted
+        if superseded:
+            old = superseded[-1].digest
+            self.entries = [
+                Entry(e.name, e.version, e.digest, e.kind, e.provenance, e.depends_on, True, e.at)
+                if old in e.depends_on else e
+                for e in self.entries
+            ]
+        self.entries.append(entry)
+        self._save()
+        return entry
+
+    def load(self, reference: str, *, replay: bool = True) -> Any:
+        """Load an artifact, replaying its fixture first unless told not to."""
+        entry = self.entry(reference)
+        path = self.root / "artifacts" / f"{entry.digest}.json"
+        if not path.exists():
+            raise MissingArtifact(f"{reference}: {entry.digest} is not in the library")
+        artifact = from_json(json.loads(path.read_text()))
+        if replay:
+            self._replay(entry, artifact)
+        return artifact
+
+    def revalidate(self, reference: str) -> Entry:
+        """Clear ``stale`` only if the recorded fixture still reproduces exactly."""
+        entry = self.entry(reference)
+        artifact = self.load(reference, replay=True)
+        _ = artifact
+        self.entries = [
+            Entry(e.name, e.version, e.digest, e.kind, e.provenance, e.depends_on, False, e.at)
+            if (e.name, e.version) == (entry.name, entry.version) else e
+            for e in self.entries
+        ]
+        self._save()
+        return self.entry(reference)
+
+    def verify(self) -> list[str]:
+        """Every artifact still present and still reproducing its fixture; problems listed."""
+        problems: list[str] = []
+        for entry in self.entries:
+            try:
+                self.load(entry.reference, replay=True)
+            except LibraryError as exc:
+                problems.append(f"{entry.reference}: {exc}")
+        return problems
+
+    def _replay(self, entry: Entry, artifact: Any) -> None:
+        path = self.root / "fixtures" / f"{entry.digest}.json"
+        if not path.exists():
+            return
+        for case in json.loads(path.read_text()):
+            facts = frozenset((p, v) for p, v in (tuple(pair) for pair in case["facts"]))
+            got = artifact.predict(facts)
+            if got != case["expect"]:
+                raise FixtureMismatch(f"{entry.reference}: fixture expected {case['expect']!r}, got {got!r}")
+
+    def _save(self) -> None:
+        tmp = self.manifest_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps([e.to_dict() for e in self.entries], indent=1, default=str))
+        tmp.replace(self.manifest_path)

tensorcode/learning/literals.py

@@ -0,0 +1,126 @@
+"""The hypothesis language: conditions over claims, generated from what was observed.
+
+Induction needs a space of candidate conditions, and the honest way to get one is
+to read it off the data rather than to write it down: every literal below is
+generated from claims that actually occurred. Nothing here names a domain.
+
+A literal costs bits (:meth:`Literal.cost`), which is what lets an induced rule
+be charged for its own description length instead of growing until it fits.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Mapping, Sequence
+
+from ..records import Claim, Ref, Store
+
+#: One case for induction: the claims that held, and the outcome to predict.
+Case = tuple[frozenset[tuple[str, Any]], Any]
+
+
+@dataclass(frozen=True)
+class Literal:
+    """A readable condition over one case's facts."""
+
+    predicate: str
+    value: Any = None
+    negated: bool = False
+    kind: str = "equals"  # "equals" | "present" | "at_least"
+
+    def holds(self, facts: Mapping[str, Any] | frozenset) -> bool:
+        table = dict(facts) if isinstance(facts, frozenset) else facts
+        got = table.get(self.predicate, _MISSING)
+        if self.kind == "present":
+            out = got is not _MISSING
+        elif self.kind == "at_least":
+            out = got is not _MISSING and isinstance(got, (int, float)) and got >= self.value
+        else:
+            out = got == self.value
+        return not out if self.negated else out
+
+    def cost(self) -> int:
+        """Bits-ish: a name, a test, and a value."""
+        return 2 + (0 if self.value is None else 1) + (1 if self.negated else 0)
+
+    def __repr__(self) -> str:
+        body = {"present": f"has({self.predicate})",
+                "at_least": f"{self.predicate}>={self.value}",
+                "equals": f"{self.predicate}={self.value!r}"}[self.kind]
+        return f"¬{body}" if self.negated else body
+
+
+class _Missing:
+    def __repr__(self) -> str:
+        return "∅"
+
+
+_MISSING = _Missing()
+
+
+def facts_of(store: Store, subject: Ref, *, predicates: Sequence[str] | None = None) -> frozenset[tuple[str, Any]]:
+    """One subject's live claims as a flat fact table (missing predicates stay missing)."""
+    out = {}
+    for record in store.claims(subject):
+        if predicates is None or record.claim.predicate in predicates:
+            out[record.claim.predicate] = record.claim.object
+    return frozenset(out.items())
+
+
+def candidate_literals(cases: Sequence[Case], *, min_count: int = 2, max_values: int = 12) -> list[Literal]:
+    """Every condition worth trying, from the values that actually occur.
+
+    A predicate seen with many distinct values contributes a presence test rather
+    than one literal per value, which keeps the space from exploding on identifiers.
+    """
+    values: dict[str, Counter] = defaultdict(Counter)
+    for facts, _ in cases:
+        for predicate, value in facts:
+            try:
+                values[predicate][value] += 1
+            except TypeError:  # unhashable objects are still worth a presence test
+                values[predicate]["<unhashable>"] += 1
+    out: list[Literal] = []
+    for predicate, counts in sorted(values.items()):
+        out.append(Literal(predicate, kind="present"))
+        out.append(Literal(predicate, kind="present", negated=True))
+        if len(counts) > max_values:
+            continue
+        for value, count in sorted(counts.items(), key=lambda kv: (-kv[1], repr(kv[0]))):
+            if count < min_count or value == "<unhashable>":
+                continue
+            out.append(Literal(predicate, value))
+            out.append(Literal(predicate, value, negated=True))
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                out.append(Literal(predicate, value, kind="at_least"))
+    return out
+
+
+def rename_case(case: Case, mapping: Mapping[Any, Any]) -> Case:
+    """A case with its symbols consistently renamed — the input to the rename control."""
+    facts, label = case
+    renamed = frozenset((p, mapping.get(v, v)) for p, v in facts)
+    return renamed, mapping.get(label, label)
+
+
+def rename_facts(facts: frozenset, mapping: Mapping[Any, Any]) -> frozenset:
+    """Rename the symbols *inside* a case, leaving its label alone.
+
+    The renaming control asks whether an artifact's output is unchanged when the
+    vocabulary changes. Renaming the labels too would make every artifact fail it,
+    which measures nothing.
+    """
+    return frozenset((p, mapping.get(v, v)) for p, v in facts)
+
+
+def rename_map(cases: Sequence[Case], *, prefix: str = "sym", labels: bool = False) -> dict[Any, Any]:
+    """A consistent, order-independent renaming of the symbols in the cases."""
+    seen: list[Any] = []
+    for facts, label in cases:
+        for _, value in facts:
+            if isinstance(value, str) and value not in seen:
+                seen.append(value)
+        if labels and isinstance(label, str) and label not in seen:
+            seen.append(label)
+    return {value: f"{prefix}{i}" for i, value in enumerate(sorted(seen))}