fanbase 0.1.0__py3-none-any.whl

fanbase/__init__.py

@@ -0,0 +1,3 @@
+"""Fanbase — a registry, evaluation framework and benchmark for Fandango specs."""
+
+__version__ = "0.1.0"

fanbase/analyze.py

@@ -0,0 +1,125 @@
+"""Summarise and correlate measurement records.
+
+The pilot's question is whether the metrics we defined actually separate — whether they
+cluster along the categories of DESIGN.md §6.3, or collapse into one axis. That is a
+correlation question, so this module computes Spearman rank correlation (rank, then
+Pearson) rather than assuming anything about metric distributions.
+
+Spearman is hand-rolled to keep the package dependency-light; the corpus is small enough
+that an O(n log n) rank and an O(n) covariance are free.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import statistics
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+# Fields that identify or describe a record rather than measure it.
+NON_METRIC_KEYS = {
+    "revision", "format", "profile", "lineage", "objective", "sha256", "path", "ok",
+    "error", "detail", "model", "effort", "replicate", "genesis", "role_hint", "arm",
+    "mode", "spec", "node_types", "fandango_version", "python_version",
+    "samples_requested", "kpaths_error",
+}
+
+
+def load(*paths: Path) -> list[dict[str, Any]]:
+    """Read JSONL result files, merging records that share a revision."""
+    merged: dict[str, dict[str, Any]] = {}
+    for path in paths:
+        for line in Path(path).read_text().splitlines():
+            if not line.strip():
+                continue
+            record = json.loads(line)
+            key = record.get("revision") or record.get("spec") or record.get("path", "")
+            merged.setdefault(key, {}).update(record)
+    return list(merged.values())
+
+
+def metric_names(records: Sequence[dict[str, Any]]) -> list[str]:
+    names: set[str] = set()
+    for record in records:
+        for key, value in record.items():
+            if key not in NON_METRIC_KEYS and isinstance(value, (int, float)) and not isinstance(value, bool):
+                names.add(key)
+    return sorted(names)
+
+
+def _ranks(values: Sequence[float]) -> list[float]:
+    """Fractional ranks, ties averaged — required for Spearman to be well defined."""
+    order = sorted(range(len(values)), key=lambda i: values[i])
+    ranks = [0.0] * len(values)
+    i = 0
+    while i < len(order):
+        j = i
+        while j + 1 < len(order) and values[order[j + 1]] == values[order[i]]:
+            j += 1
+        shared = (i + j) / 2 + 1
+        for k in range(i, j + 1):
+            ranks[order[k]] = shared
+        i = j + 1
+    return ranks
+
+
+def spearman(xs: Sequence[float], ys: Sequence[float]) -> float | None:
+    if len(xs) < 3:
+        return None
+    rx, ry = _ranks(xs), _ranks(ys)
+    mx, my = statistics.fmean(rx), statistics.fmean(ry)
+    num = sum((a - mx) * (b - my) for a, b in zip(rx, ry))
+    den = math.sqrt(sum((a - mx) ** 2 for a in rx) * sum((b - my) ** 2 for b in ry))
+    return round(num / den, 3) if den else None
+
+
+def paired(records: Iterable[dict[str, Any]], a: str, b: str) -> tuple[list[float], list[float]]:
+    xs, ys = [], []
+    for record in records:
+        va, vb = record.get(a), record.get(b)
+        if isinstance(va, (int, float)) and isinstance(vb, (int, float)):
+            xs.append(float(va))
+            ys.append(float(vb))
+    return xs, ys
+
+
+@dataclass
+class Summary:
+    metric: str
+    n: int
+    mean: float
+    median: float
+    minimum: float
+    maximum: float
+
+
+def summarise(records: Sequence[dict[str, Any]], metrics: Sequence[str] | None = None) -> list[Summary]:
+    out = []
+    for name in metrics or metric_names(records):
+        values = [float(r[name]) for r in records
+                  if isinstance(r.get(name), (int, float)) and not isinstance(r.get(name), bool)]
+        if values:
+            out.append(Summary(name, len(values), round(statistics.fmean(values), 3),
+                               round(statistics.median(values), 3), min(values), max(values)))
+    return out
+
+
+def group_by(records: Sequence[dict[str, Any]], key: str) -> dict[Any, list[dict[str, Any]]]:
+    groups: dict[Any, list[dict[str, Any]]] = defaultdict(list)
+    for record in records:
+        groups[record.get(key)].append(record)
+    return dict(groups)
+
+
+def correlation_matrix(
+    records: Sequence[dict[str, Any]], metrics: Sequence[str], min_pairs: int = 5
+) -> dict[tuple[str, str], float | None]:
+    matrix: dict[tuple[str, str], float | None] = {}
+    for i, a in enumerate(metrics):
+        for b in metrics[i + 1:]:
+            xs, ys = paired(records, a, b)
+            matrix[(a, b)] = spearman(xs, ys) if len(xs) >= min_pairs else None
+    return matrix

fanbase/cli.py

@@ -0,0 +1,264 @@
+"""The `fanbase` command.
+
+Everything here reads a registry checkout and nothing else — no upstream corpus, no
+network, and no Fandango import unless a subcommand actually measures something.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+from fanbase.registry import Registry, RegistryError, Revision
+from fanbase.runner import METRICS, RunConfig, run
+from fanbase.analyze import correlation_matrix, group_by, load, metric_names, summarise
+from fanbase.importers.corpus import import_corpus
+from fanbase.validate import validate
+
+ENV_REGISTRY = "FANBASE_REGISTRY"
+
+
+def find_registry(explicit: str | None) -> Registry:
+    """Locate a registry: --registry, then $FANBASE_REGISTRY, then upwards from cwd."""
+    candidates: list[Path] = []
+    if explicit:
+        candidates.append(Path(explicit))
+    if os.environ.get(ENV_REGISTRY):
+        candidates.append(Path(os.environ[ENV_REGISTRY]))
+    here = Path.cwd().resolve()
+    candidates.extend([here, *here.parents])
+
+    for candidate in candidates:
+        if (candidate / "specs").is_dir():
+            return Registry(candidate)
+    raise RegistryError(
+        "no registry found. Pass --registry PATH, set $FANBASE_REGISTRY, "
+        "or run inside a checkout containing specs/"
+    )
+
+
+def install_root() -> Path:
+    """Where Fandango's `include()` will find installed specs.
+
+    Mirrors Fandango's own search order, so an installed spec is importable with no
+    further configuration.
+    """
+    if fandango_path := os.environ.get("FANDANGO_PATH"):
+        first = fandango_path.split(os.pathsep)[0]
+        if first:
+            return Path(first)
+    if xdg := os.environ.get("XDG_DATA_HOME"):
+        return Path(xdg) / "fandango"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Fandango"
+    return Path.home() / ".local" / "share" / "fandango"
+
+
+def describe(rev: Revision) -> list[tuple[str, str]]:
+    header = rev.spec.header
+    rows = [
+        ("revision", str(rev.coord)),
+        ("objective", rev.objective),
+        ("sha256", rev.spec.sha256[:16]),
+        ("size", f"{rev.spec.size:,} bytes / {rev.spec.lines} lines"),
+    ]
+    for field in ("MODEL", "EFFORT", "REPLICATE", "GENESIS", "PROFILE", "ROLE_HINT", "SOURCE"):
+        if field in header:
+            rows.append((field.lower(), str(header[field])))
+    return rows
+
+
+def cmd_list(args, reg: Registry) -> int:
+    formats = reg.formats()
+    for fmt in formats:
+        profiles = reg.profiles(fmt)
+        n = sum(len(reg.lineages(fmt, p)) for p in profiles)
+        print(f"  {fmt:<16} {len(profiles)} profile(s)  {n:>4} lineage(s)")
+    print(f"\n{len(formats)} formats")
+    return 0
+
+
+def cmd_search(args, reg: Registry) -> int:
+    needle = args.query.lower()
+    hits = 0
+    for fmt in reg.formats():
+        if needle in fmt.lower():
+            print(f"  {fmt}")
+            hits += 1
+            continue
+        for profile in reg.profiles(fmt):
+            for lineage in reg.lineages(fmt, profile):
+                if needle in lineage.lower():
+                    print(f"  {fmt}/{profile}/{lineage}")
+                    hits += 1
+    print(f"\n{hits} match(es) for {args.query!r}")
+    return 0 if hits else 1
+
+
+def cmd_show(args, reg: Registry) -> int:
+    rev = reg.resolve(args.ref)
+    width = max(len(k) for k, _ in describe(rev))
+    for key, value in describe(rev):
+        print(f"  {key:<{width}}  {value}")
+    return 0
+
+
+def cmd_install(args, reg: Registry) -> int:
+    rev = reg.resolve(args.ref)
+    root = Path(args.into) if args.into else install_root()
+    target = root / rev.coord.format / f"{rev.coord.lineage}.fan"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(rev.path, target)
+    print(f"installed {rev.coord} -> {target}")
+    print(f'  include("{rev.coord.format}/{rev.coord.lineage}.fan")')
+    return 0
+
+
+def cmd_measure(args, reg: Registry) -> int:
+    revisions = list(reg.revisions(fmt=args.format))
+    if args.objective:
+        revisions = [r for r in revisions if r.objective == args.objective]
+    if not revisions:
+        print("no revisions matched", file=sys.stderr)
+        return 1
+    config = RunConfig(
+        metric=args.metric,
+        python=args.python or sys.executable,
+        timeout=args.timeout,
+        jobs=args.jobs,
+        extra=tuple(shlex.split(args.extra or "")),
+    )
+    ok, failed = run(reg, config, Path(args.out), revisions=revisions)
+    print(f"\n{ok} measured, {failed} failed -> {args.out}")
+    return 0
+
+
+def cmd_analyze(args, reg: Registry) -> int:
+    records = load(*[Path(p) for p in args.results])
+    ok = [r for r in records if r.get("ok")]
+    print(f"records {len(records)}  ok {len(ok)}  failed {len(records) - len(ok)}")
+    versions = {r.get("fandango_version") for r in ok if r.get("fandango_version")}
+    if versions:
+        print(f"fandango {', '.join(sorted(versions))}")
+    if not ok:
+        return 1
+
+    metrics = [m for m in (args.metrics or metric_names(ok))]
+    print("\nmetric summary")
+    print(f"  {'metric':<26} {'n':>5} {'mean':>10} {'median':>10} {'min':>10} {'max':>10}")
+    for s in summarise(ok, metrics):
+        print(f"  {s.metric:<26} {s.n:>5} {s.mean:>10} {s.median:>10} {s.minimum:>10} {s.maximum:>10}")
+
+    for key in args.by or []:
+        groups = {k: v for k, v in group_by(ok, key).items() if k is not None}
+        if len(groups) < 2:
+            continue
+        print(f"\nby {key}")
+        shown = [m for m in metrics if any(m in r for r in ok)][: args.columns]
+        print(f"  {key:<28} {'n':>4} " + " ".join(f"{m[:14]:>15}" for m in shown))
+        for name, rows in sorted(groups.items(), key=lambda kv: str(kv[0])):
+            cells = []
+            for m in shown:
+                s = summarise(rows, [m])
+                cells.append(f"{s[0].mean:>15}" if s else f"{'-':>15}")
+            print(f"  {str(name):<28} {len(rows):>4} " + " ".join(cells))
+
+    if args.correlate:
+        matrix = correlation_matrix(ok, metrics)
+        ranked = sorted(
+            ((v, a, b) for (a, b), v in matrix.items() if v is not None),
+            key=lambda t: -abs(t[0]),
+        )
+        print(f"\nstrongest rank correlations (Spearman, {len(ranked)} pairs)")
+        for value, a, b in ranked[: args.top]:
+            print(f"  {value:>7}  {a}  ~  {b}")
+    return 0
+
+
+def cmd_import(args, reg: Registry) -> int:
+    written, unchanged, formats = import_corpus(Path(args.corpus), reg.root, args.dry_run)
+    verb = "would write" if args.dry_run else "wrote"
+    print(f"{verb} {written} revisions, {unchanged} unchanged, across {formats} formats")
+    return 0
+
+
+def cmd_validate(args, reg: Registry) -> int:
+    problems = list(validate(reg))
+    errors = [p for p in problems if p.level == "error"]
+    shown = problems if args.all else problems[: args.limit]
+    for problem in shown:
+        print(f"  {problem}")
+    if len(problems) > len(shown):
+        print(f"  ... and {len(problems) - len(shown)} more (use --all)")
+    print(f"\n{len(errors)} error(s), {len(problems) - len(errors)} warning(s)")
+    return 1 if errors else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="fanbase", description=__doc__)
+    ap.add_argument("--registry", help="path to a registry checkout")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("list", help="list formats in the registry").set_defaults(fn=cmd_list)
+
+    p = sub.add_parser("search", help="find formats and lineages")
+    p.add_argument("query")
+    p.set_defaults(fn=cmd_search)
+
+    p = sub.add_parser("show", help="show one revision")
+    p.add_argument("ref", help="e.g. png/base/normal-claude-sonnet-5-high-r1@v1")
+    p.set_defaults(fn=cmd_show)
+
+    p = sub.add_parser("install", help="copy a revision into Fandango's include path")
+    p.add_argument("ref")
+    p.add_argument("--into", help="install directory (default: Fandango's data dir)")
+    p.set_defaults(fn=cmd_install)
+
+    p = sub.add_parser("analyze", help="summarise and correlate measurement records")
+    p.add_argument("results", nargs="+", help="JSONL files from `fanbase measure`")
+    p.add_argument("--metrics", nargs="*", help="restrict to these metrics")
+    p.add_argument("--by", nargs="*", default=["objective", "model", "effort"],
+                   help="group comparisons on these fields")
+    p.add_argument("--correlate", action="store_true", help="rank-correlate every metric pair")
+    p.add_argument("--top", type=int, default=15)
+    p.add_argument("--columns", type=int, default=4)
+    p.set_defaults(fn=cmd_analyze)
+
+    p = sub.add_parser("import", help="import an upstream corpus into the registry")
+    p.add_argument("corpus")
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(fn=cmd_import)
+
+    p = sub.add_parser("validate", help="check the registry against its schemas")
+    p.add_argument("--limit", type=int, default=25)
+    p.add_argument("--all", action="store_true")
+    p.set_defaults(fn=cmd_validate)
+
+    p = sub.add_parser("measure", help="run a metric over registry revisions")
+    p.add_argument("--metric", choices=sorted(METRICS), default="intrinsics")
+    p.add_argument("--format", help="restrict to one format")
+    p.add_argument("--objective", help="restrict to one objective")
+    p.add_argument("--python", help="interpreter with Fandango (default: this one)")
+    p.add_argument("--timeout", type=int, default=120)
+    p.add_argument("--jobs", type=int, default=1)
+    p.add_argument("--out", default="results/metrics.jsonl")
+    p.add_argument("--extra", help='extra worker arguments, one string: --extra "--samples 8"')
+    p.set_defaults(fn=cmd_measure)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.fn(args, find_registry(args.registry))
+    except RegistryError as exc:
+        print(f"fanbase: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fanbase/importers/__init__.py

@@ -0,0 +1,6 @@
+"""Adapters that turn an external, ad-hoc corpus into registry entries.
+
+Everything source-specific lives here. The rest of the package knows only the
+registry layout (`fanbase.registry`), so no core code, CLI command, metric, or site
+build ever depends on how some upstream repository happened to name its files.
+"""

fanbase/importers/corpus.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Import an upstream corpus into the registry (DESIGN.md §4).
+
+Re-runnable and idempotent: every imported revision records the SHA-256 of the file it
+came from, so re-importing an updated corpus rewrites what changed, adds what is new,
+and leaves everything else untouched.
+
+Upstream specs carry no provenance header, so one is generated from the source's
+filename and prepended — that is what makes a registry spec self-describing when someone
+copies the single file into their own project.
+
+Canonical specs are deliberately *not* created: blessing one is a maintainer decision
+informed by measurements, never an import-time guess.
+
+Exposed as `fanbase import CORPUS`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from fanbase.importers.ossfuzz_eval import describe, load_corpus
+from fanbase.registry import DEFAULT_OBJECTIVE, DEFAULT_PROFILE
+
+GENERATED_BANNER = "# --- generated by fanbase import; edit the registry, not this block ---"
+
+
+def _yaml(mapping: dict[str, object]) -> str:
+    """Minimal YAML writer — avoids a dependency for what is only flat key/value data."""
+    lines = []
+    for key, value in mapping.items():
+        if value is None:
+            lines.append(f"{key}:")
+        elif isinstance(value, bool):
+            lines.append(f"{key}: {'true' if value else 'false'}")
+        elif isinstance(value, (int, float)):
+            lines.append(f"{key}: {value}")
+        elif isinstance(value, list):
+            # An empty list must stay a list: `key:` alone parses back as null.
+            if not value:
+                lines.append(f"{key}: []")
+            else:
+                lines.append(f"{key}:")
+                lines.extend(f"  - {item}" for item in value)
+        else:
+            text = str(value).replace('"', '\\"')
+            lines.append(f'{key}: "{text}"')
+    return "\n".join(lines) + "\n"
+
+
+def build_header(name, source_sha: str, source_rel: str) -> str:
+    objective = name.objective or DEFAULT_OBJECTIVE
+    fields = {
+        "INFO": f"Fandango specification for {name.format}",
+        "PROFILE": f"{name.format}/{DEFAULT_PROFILE}",
+        "OBJECTIVE": objective,
+        "GENESIS": "ai",
+        "MODEL": name.model or "unknown",
+        "EFFORT": name.effort or "unknown",
+        "REPLICATE": name.replicate,
+        "SOURCE": source_rel,
+        "SOURCE_SHA256": source_sha,
+    }
+    if name.role_hint:
+        fields["ROLE_HINT"] = name.role_hint
+    lines = [GENERATED_BANNER]
+    for key, value in fields.items():
+        lines.append(f"{key} = {value!r}" if isinstance(value, int) else f'{key} = "{value}"')
+    lines.append(GENERATED_BANNER)
+    return "\n".join(lines) + "\n\n"
+
+
+def strip_generated_header(text: str) -> str:
+    """Remove a previously generated block so re-import compares like with like."""
+    if not text.startswith(GENERATED_BANNER):
+        return text
+    end = text.find(GENERATED_BANNER, len(GENERATED_BANNER))
+    return text[end + len(GENERATED_BANNER):].lstrip("\n") if end != -1 else text
+
+
+def write_if_changed(path: Path, content: str, dry_run: bool) -> bool:
+    if path.exists() and path.read_text(encoding="utf-8") == content:
+        return False
+    if not dry_run:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    return True
+
+
+def import_corpus(corpus: Path, root: Path, dry_run: bool = False) -> tuple[int, int, int]:
+    """Import `corpus` into the registry at `root`. Returns (written, unchanged, formats)."""
+    specs = load_corpus(Path(corpus).resolve())
+    root = Path(root).resolve()
+    args = type("Args", (), {"dry_run": dry_run})()
+    written = skipped = 0
+    formats: dict[str, set[str]] = {}
+
+    for spec in specs:
+        name = describe(spec)
+        lineage = name.lineage if name.recognised else f"legacy-{spec.path.stem}"
+        formats.setdefault(name.format, set()).add(lineage)
+
+        body = strip_generated_header(spec.path.read_text(encoding="utf-8", errors="replace"))
+        source_sha = hashlib.sha256(body.encode("utf-8")).hexdigest()
+        content = build_header(name, source_sha, spec.rel.as_posix()) + body
+
+        base = root / "specs" / name.format / "profiles" / DEFAULT_PROFILE / "lineages" / lineage
+        changed = write_if_changed(base / "v1.fan", content, args.dry_run)
+        write_if_changed(base / "lineage.yaml", _yaml({
+            "id": lineage,
+            "objective": name.objective or DEFAULT_OBJECTIVE,
+            "role_hint": name.role_hint,
+            "model": name.model,
+            "effort": name.effort,
+            "replicate": name.replicate,
+            "arm": name.arm,
+            "owner": None,
+            "concept_doi": None,
+        }), args.dry_run)
+        written += changed
+        skipped += not changed
+
+    for fmt, lineages in sorted(formats.items()):
+        base = root / "specs" / fmt
+        write_if_changed(base / "format.yaml", _yaml({
+            "id": fmt,
+            "name": fmt.upper(),
+            "category": None,
+            "references": [],
+            "oracle_tier": "T0",
+            "maintainers": [],
+        }), args.dry_run)
+        write_if_changed(base / "profiles.yaml", _yaml({
+            "default": DEFAULT_PROFILE,
+            "profiles": [DEFAULT_PROFILE],
+        }), args.dry_run)
+        write_if_changed(base / "profiles" / DEFAULT_PROFILE / "profile.yaml", _yaml({
+            "id": DEFAULT_PROFILE,
+            "note": "placeholder: upstream declares no format version",
+            "extends": None,
+            "lineages": len(lineages),
+        }), args.dry_run)
+
+    return written, skipped, len(formats)

fanbase/importers/ossfuzz_eval.py

@@ -0,0 +1,112 @@
+"""Import adapter for the `oss-fuzz-fandango-eval` corpus.
+
+That repository is a factorial generation experiment, not a registry: every spec is one
+cell of `format x mode x model x effort x replicate`, encoded in the filename as
+
+    <format>_<mode>_<model>_<effort>_<replicate>.fan
+    png_spicy_claude-opus-4-8_high_2.fan
+
+with two arms — `library-broad/` (many formats, shallow) and `library-deep/` (few
+formats, the full grid). This module is the only place in the package that knows any of
+that; everything else consumes `fanbase.registry`.
+
+Two mappings are not one-to-one and are deliberate:
+
+* `mode` conflates two of our dimensions. `normal` and `spicy` are *objectives* (breadth
+  vs boundary), while `modify` describes the *role* the spec is written for (MUTATE) and
+  says nothing about what it aims at. Both are emitted separately.
+* A replicate is **not** a revision. Three independent generations under identical
+  settings are siblings, not successive improvements, so each becomes its own lineage at
+  `v1` rather than `v1..v3` of one lineage. Revisions stay reserved for real patches.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from fanbase.spec import SpecFile, discover, group_by_content
+
+# normal/spicy describe what the spec aims at; modify describes how it is meant to be used.
+OBJECTIVE_BY_MODE = {"normal": "breadth", "spicy": "boundary"}
+ROLE_BY_MODE = {"modify": "mutate"}
+
+EFFORTS = ("low", "medium", "high", "minimal", "none")
+
+_NAME = re.compile(
+    r"^(?P<format>[^_]+)_(?P<mode>[^_]+)_(?P<model>.+?)_"
+    r"(?P<effort>" + "|".join(EFFORTS) + r")_(?P<replicate>\d+)$"
+)
+
+
+@dataclass
+class ParsedName:
+    stem: str
+    format: str
+    mode: str | None = None
+    model: str | None = None
+    effort: str | None = None
+    replicate: int | None = None
+    arm: str | None = None          # broad | deep
+    recognised: bool = False
+
+    @property
+    def objective(self) -> str | None:
+        return OBJECTIVE_BY_MODE.get(self.mode or "")
+
+    @property
+    def role_hint(self) -> str | None:
+        return ROLE_BY_MODE.get(self.mode or "")
+
+    @property
+    def lineage(self) -> str:
+        """Experimental cell, replicate included — siblings are separate lineages."""
+        if not self.recognised:
+            return "legacy"
+        return f"{self.mode}-{self.model}-{self.effort}-r{self.replicate}"
+
+
+def parse_spec_name(stem: str, arm: str | None = None) -> ParsedName:
+    m = _NAME.match(stem)
+    if not m:
+        return ParsedName(stem=stem, format=stem.split("_")[0].split("-")[0], arm=arm)
+    return ParsedName(
+        stem=stem,
+        format=m.group("format"),
+        mode=m.group("mode"),
+        model=m.group("model"),
+        effort=m.group("effort"),
+        replicate=int(m.group("replicate")),
+        arm=arm,
+        recognised=True,
+    )
+
+
+def arm_of(spec: SpecFile) -> str | None:
+    head = spec.rel.parts[0] if spec.rel.parts else ""
+    return head.removeprefix("library-") if head.startswith("library-") else None
+
+
+def format_dir(spec: SpecFile) -> str:
+    """The format directory, which sits under the arm: `library-broad/png/library/...`."""
+    parts = spec.rel.parts
+    return parts[1] if len(parts) > 2 and parts[0].startswith("library-") else parts[0]
+
+
+def describe(spec: SpecFile) -> ParsedName:
+    return parse_spec_name(spec.path.stem, arm_of(spec))
+
+
+def distinct(specs: list[SpecFile]) -> list[SpecFile]:
+    """One representative per content hash.
+
+    Identical content across two experimental cells is itself a finding — two models
+    converging on the same grammar — so callers that care should use `group_by_content`.
+    """
+    chosen = [group[0] for group in group_by_content(specs).values()]
+    return sorted(chosen, key=lambda s: s.rel.as_posix())
+
+
+def load_corpus(root: Path) -> list[SpecFile]:
+    return sorted(discover(Path(root)), key=lambda s: s.rel.as_posix())

fanbase/metrics/__init__.py

@@ -0,0 +1,12 @@
+"""Metric implementations, grouped by the apparatus they require (DESIGN.md §6.2).
+
+  S   the spec alone           intrinsics, self-consistency
+  +I  a seed corpus            recall, round-trip against real inputs, invariant battery
+  +R  a reference layout       structural fidelity
+  +O  a validity oracle        validity rate, specificity
+  +C  instrumented program     target coverage, feature reach
+  +F  a program fleet + time   finding yield
+
+Anything below `+O` runs in CI on every PR; `+C` and `+F` need the lab machine and
+repeated trials, and a single number from them is not a result.
+"""