quiverlab 0.1.0__py3-none-any.whl

quiverlab/__init__.py

@@ -0,0 +1,42 @@
+"""quiverlab: quivers with relations and Hochschild theory, exactly."""
+
+__version__ = "0.1.0"
+
+# Worked-steps traces are ON by default (spec D9). Flip per-call via
+# A.hochschild_cohomology(..., verbose=False) or globally via quiverlab.verbose.
+verbose = True
+
+from quiverlab.errors import (  # noqa: E402,F401
+    QuiverlabError, ExactnessError, FieldError, RelationError,
+    AdmissibilityError, NotFiniteDimensionalError, DepthLimitError,
+    QpaUnavailableError,
+)
+from quiverlab.fields import GF  # noqa: E402,F401
+from quiverlab.fields import CC, E  # noqa: E402,F401
+from quiverlab.fields import QQi  # noqa: E402,F401
+from quiverlab.combinat import Quiver  # noqa: E402,F401
+from quiverlab.core import Algebra  # noqa: E402,F401
+from quiverlab.families import linear_path_algebra, truncated_polynomial  # noqa: E402,F401
+from quiverlab.families import (  # noqa: E402,F401
+    NakayamaAlgebra, PathAlgebra, TruncatedPathAlgebra, RadicalSquareZero,
+    IncidenceAlgebra, QuantumCI, ExteriorAlgebra, PreprojectiveAlgebra,
+    TrivialExtension, TensorProduct, zoo, families,
+)
+from quiverlab.citations import bibliography  # noqa: E402,F401
+from quiverlab.invariants.sweep import sweep  # noqa: E402,F401
+
+__all__ = [
+    "__version__",
+    "verbose",
+    "QuiverlabError", "ExactnessError", "FieldError", "RelationError",
+    "AdmissibilityError", "NotFiniteDimensionalError", "DepthLimitError",
+    "QpaUnavailableError",
+    "GF", "CC", "E", "QQi",
+    "Quiver", "Algebra",
+    "truncated_polynomial", "linear_path_algebra",
+    "NakayamaAlgebra", "PathAlgebra", "TruncatedPathAlgebra", "RadicalSquareZero",
+    "IncidenceAlgebra", "QuantumCI", "ExteriorAlgebra", "PreprojectiveAlgebra",
+    "TrivialExtension", "TensorProduct", "zoo", "families",
+    "bibliography",
+    "sweep",
+]

quiverlab/batch/__init__.py

@@ -0,0 +1,20 @@
+"""quiverlab.batch: SQLite persistence + scan driver for family sweeps.
+
+Expert-facing; deliberately NOT exported at the quiverlab top level -- reach it via
+``import quiverlab.batch``.  This package is the quiverlab lift of hanlab's ``labdb``
+(Marco Armenta's HansConjecture, MIT): the pure ``analyze(spec) -> record`` unit of
+work, the named family builder registry, and the ``ResultsDB`` SQLite store with the
+Han counterexample-search queries.
+
+  quiverlab.batch.db.ResultsDB       -- SQLite results store (context manager)
+  quiverlab.batch.builders.BUILDERS  -- {name: builder}; build_algebra(spec)
+  quiverlab.batch.scan.analyze       -- pure spec -> JSON record; run_scan(specs, n_workers)
+  quiverlab.batch.PRIME              -- the char-0 proxy prime, 32003
+"""
+from quiverlab.batch import builders, db, scan  # noqa: F401
+# Package-level surface frozen for Plans 07/09 (see Plan-06 Task-14 freeze).
+from quiverlab.batch.builders import BUILDERS, build_algebra  # noqa: F401
+from quiverlab.batch.db import ResultsDB  # noqa: F401
+from quiverlab.batch.scan import (  # noqa: F401
+    PRIME, analyze, depth_for_dim, han_verdict, max_term_dim_for_dim,
+    open_zoo_to_specs, run_scan)

quiverlab/batch/builders.py

@@ -0,0 +1,68 @@
+"""Builder registry: name -> callable(*args) -> quiverlab Algebra (quiverlab.batch).
+
+Adapted from hanlab's ``labdb`` builder registry (Marco Armenta's HansConjecture,
+MIT): the same catalog of named families, but each name now resolves to the
+corresponding quiverlab family constructor.  Every builder threads an optional
+``field`` (default: the family's own default, exact CC) so ``scan.analyze`` can
+rebuild an algebra over GF(p) for the exact F_p Hochschild computation.
+
+The six core builders (mapped per the Plan-06 brief):
+  truncated_polynomial(a)        -> families.basic.truncated_polynomial(a)
+  quantum_ci(c)                  -> families.QuantumCI(q=c)
+  cyclic_nakayama(n, ell)        -> families.NakayamaAlgebra(n=n, l=ell, cyclic=True)
+  linear_path_algebra(n)         -> families.basic.linear_path_algebra(n)
+  dynkin(typ, n)                 -> families.PathAlgebra(f"{typ}{n}")
+  reduction_system(ngen, rules, name)
+                                 -> families.zoo.build_from_record({...})   (open zone)
+"""
+from quiverlab.families import basic
+from quiverlab.families.nakayama import NakayamaAlgebra
+from quiverlab.families.path_algebra import PathAlgebra
+from quiverlab.families.quantum import QuantumCI
+from quiverlab.families.zoo import build_from_record as _build_from_record
+
+
+def _truncated_polynomial(a, field=None):
+    return basic.truncated_polynomial(a, field=field)
+
+
+def _quantum_ci(c, field=None):
+    return QuantumCI(q=c, field=field)
+
+
+def _cyclic_nakayama(n, ell, field=None):
+    return NakayamaAlgebra(n=n, l=ell, cyclic=True, field=field)
+
+
+def _linear_path_algebra(n, field=None):
+    return basic.linear_path_algebra(n, field=field)
+
+
+def _dynkin(typ, n, field=None):
+    return PathAlgebra(f"{typ}{n}", field=field)
+
+
+def _reduction_system(ngen, rules, name, arrows=None, vertices=None, field=None):
+    """Open-zone builder: materialise A = k<g>/I from a confluent reduction system,
+    routed through quiverlab's zoo reduction-system -> Algebra path.  Multi-vertex
+    records (Plan 18) carry arrows/vertices; legacy args are byte-unchanged."""
+    rec = {"ngen": ngen, "rules": rules, "name": name, "dim": None}
+    if arrows is not None:
+        rec["arrows"] = arrows
+        rec["vertices"] = vertices
+    return _build_from_record(rec, field=field)
+
+
+BUILDERS = {
+    "truncated_polynomial": _truncated_polynomial,   # (a,)
+    "quantum_ci": _quantum_ci,                        # (c,)
+    "cyclic_nakayama": _cyclic_nakayama,              # (n, ell)
+    "linear_path_algebra": _linear_path_algebra,      # (n,)
+    "dynkin": _dynkin,                                # (typ, n)
+    "reduction_system": _reduction_system,            # (ngen, rules, name) -- open zone
+}
+
+
+def build_algebra(spec):
+    """Construct the quiverlab Algebra named by a spec dict (builder + args)."""
+    return BUILDERS[spec["builder"]](*spec.get("args", []))

quiverlab/batch/db.py

@@ -0,0 +1,157 @@
+"""SQLite results database for batch scans (quiverlab.batch).
+
+Ported verbatim (schema, migration, queries) from hanlab's ``labdb.ResultsDB``
+-- Marco Armenta's ``HansConjecture`` codebase (MIT), the "B4" results-database
+component.  Only the module docstring and the surrounding package layout are
+quiverlab's; the SQLite schema, the ``_migrate_open_columns`` back-compat path,
+``_nullable_bool`` and every query method are the bank's, kept faithful so a
+quiverlab scan DB round-trips byte-for-byte with a hanlab one.
+
+``ResultsDB`` persists ``scan.analyze`` records to SQLite, indexed by complexity
+and structural data, and exposes the counterexample-search queries the Han
+programme needs -- in particular ``bounded_homology_candidates()`` ("bounded HH
+but apparently infinite global dimension", the shape of a Han counterexample) and
+``asymmetric()`` ("HH_* and HH^* have different complexity").  Records are stored
+as exact JSON (ints/strings; no floats): ``record_json`` is the full record and
+the promoted columns are exact copies of its scalar fields.
+"""
+
+import json
+import sqlite3
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS results (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    name          TEXT,
+    builder       TEXT,
+    args          TEXT,
+    dim           INTEGER,
+    N             INTEGER,
+    associative   INTEGER,
+    cx_homology   TEXT,
+    cx_cohomology TEXT,
+    asymmetric    INTEGER,
+    homology_bounded      INTEGER,
+    homology_nonzero_tail INTEGER,
+    kind          TEXT,                 -- 'open' for reduction_system rows, else NULL
+    han_verdict   TEXT,                 -- open zone: nonzero-tail / COUNTEREXAMPLE? / ...
+    growth        TEXT,                 -- open zone: bounded / growing / ?
+    depth_reached INTEGER,              -- open zone: last HH_* degree computed
+    truncated_at  INTEGER,              -- open zone: degree the budget stopped at, or NULL
+    record_json   TEXT,
+    UNIQUE(builder, args, N)
+);
+CREATE INDEX IF NOT EXISTS idx_cx ON results(cx_homology, cx_cohomology);
+CREATE INDEX IF NOT EXISTS idx_asym ON results(asymmetric);
+CREATE INDEX IF NOT EXISTS idx_verdict ON results(han_verdict);
+"""
+
+
+def _nullable_bool(v):
+    """None -> None (SQL NULL); else 0/1.  Open-zone records have asymmetric=None,
+    which must not be lossily collapsed to 0 ('symmetric')."""
+    return None if v is None else int(bool(v))
+
+
+class ResultsDB:
+    """SQLite store for scan records, with the counterexample-search queries."""
+
+    def __init__(self, path=":memory:"):
+        self.conn = sqlite3.connect(path)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.executescript(_SCHEMA)
+        self._migrate_open_columns()        # backward-compat for old on-disk DBs
+        self.conn.commit()
+
+    def _migrate_open_columns(self):
+        """Add the open-zone columns to a pre-existing table that lacks them.
+
+        No-op on a DB created with the current _SCHEMA -- the supported path always
+        builds the DB fresh, so this is belt-and-suspenders for ad-hoc reuse of a
+        stale on-disk file (its pre-existing rows backfill as NULL)."""
+        have = {r["name"] for r in self.conn.execute("PRAGMA table_info(results)")}
+        for col, decl in (("kind", "TEXT"), ("han_verdict", "TEXT"),
+                          ("growth", "TEXT"), ("depth_reached", "INTEGER"),
+                          ("truncated_at", "INTEGER")):
+            if col not in have:
+                self.conn.execute(f"ALTER TABLE results ADD COLUMN {col} {decl}")
+
+    def close(self):
+        self.conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()
+
+    def insert(self, rec):
+        """Insert (or replace) one analyze() record (structural or open-zone).
+
+        The five open-zone columns are read with `.get(...)`, so a structural record
+        (which lacks them) writes NULL -- backward compatible."""
+        self.conn.execute(
+            """INSERT OR REPLACE INTO results
+               (name, builder, args, dim, N, associative, cx_homology, cx_cohomology,
+                asymmetric, homology_bounded, homology_nonzero_tail,
+                kind, han_verdict, growth, depth_reached, truncated_at, record_json)
+               VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+            (
+                rec.get("name"),
+                rec.get("builder"),
+                json.dumps(rec.get("args", [])),
+                rec.get("dim"),
+                rec.get("N"),
+                int(rec.get("associative", False)),
+                str(rec.get("cx_homology")),
+                str(rec.get("cx_cohomology")),
+                _nullable_bool(rec.get("asymmetric")),    # open: None -> SQL NULL
+                int(rec.get("homology_bounded", False)),
+                int(rec.get("homology_nonzero_tail", False)),
+                rec.get("kind"),                          # 'open' or None
+                rec.get("han_verdict"),                   # str or None
+                rec.get("growth"),                        # str or None
+                rec.get("depth_reached"),                 # int or None
+                rec.get("truncated_at"),                  # int or None
+                json.dumps(rec),
+            ),
+        )
+        self.conn.commit()
+
+    def insert_many(self, recs):
+        for r in recs:
+            self.insert(r)
+
+    def all(self):
+        return [json.loads(r["record_json"])
+                for r in self.conn.execute("SELECT record_json FROM results")]
+
+    def query(self, where, params=()):
+        rows = self.conn.execute(
+            f"SELECT record_json FROM results WHERE {where}", params)
+        return [json.loads(r["record_json"]) for r in rows]
+
+    def asymmetric(self):
+        """Algebras whose HH_* and HH^* have different apparent complexity."""
+        return self.query("asymmetric = 1")
+
+    def bounded_homology_candidates(self):
+        """Counterexample-shaped rows (associative): (i) bounded HH_* -- not obviously
+        gl.dim finite (structural + open), OR (ii) open-zone rows whose HH_* vanished in
+        high degree (han_verdict='COUNTEREXAMPLE?').  `han_verdict` is NULL on structural
+        rows, so the second disjunct never changes their behavior."""
+        return self.query(
+            "associative = 1 AND "
+            "(homology_bounded = 1 OR han_verdict = 'COUNTEREXAMPLE?')"
+        )
+
+    def open_counterexample_candidates(self):
+        """Open-zone rows whose HH_* appears to vanish in high degree (the literal
+        Han-counterexample shape); indexed by idx_verdict."""
+        return self.query("han_verdict = 'COUNTEREXAMPLE?'")
+
+    def by_complexity(self, cx_homology):
+        return self.query("cx_homology = ?", (str(cx_homology),))
+
+    def __len__(self):
+        return self.conn.execute("SELECT COUNT(*) FROM results").fetchone()[0]

quiverlab/batch/scan.py

@@ -0,0 +1,257 @@
+"""Pure per-algebra analysis + scan driver (quiverlab.batch).
+
+Adapted from hanlab's ``labdb.analyze`` / ``_analyze_open`` / ``run_scan`` (Marco
+Armenta's HansConjecture, MIT).  The per-algebra computation is a **pure function**
+``analyze(spec) -> record``: a ``spec`` is a small JSON-serializable description
+``{"builder", "args", "N", "primes"}`` and ``analyze`` builds the algebra from the
+builder registry, computes HH_* and HH^* over the requested primes, the apparent
+complexities, and the homology/cohomology asymmetry, and returns a JSON record.
+``run_scan`` drives a list of specs -- single-worker by default; the same
+``analyze`` is the unit of work for a SLURM array on a cluster (one spec per task,
+merge the JSON afterwards -- no shared state).
+
+Structural builders route through the exact F_p Hochschild engine
+(``Algebra.hochschild_homology`` / ``hochschild_cohomology`` over GF(PRIME)) plus
+the apparent-complexity classifier ``scan3.complexity_of``.  The ``reduction_system``
+builder routes to the open-zone minimal A^e-resolution path.  The ``scan_open``
+policy helpers ``han_verdict`` / ``depth_for_dim`` / ``max_term_dim_for_dim`` are
+ported verbatim from hanlab.scan_open below.
+
+All record values are exact ints / strings (dims are ints; complexities are ints
+or the sentinel string ``'>=2'``) -- there is no float round-trip anywhere.
+"""
+from quiverlab.batch.builders import BUILDERS
+from quiverlab.fields import GF
+
+PRIME = 32003
+
+
+# ---------------------------------------------------------------------------
+# scan_open policy helpers -- ported verbatim from hanlab.scan_open (MIT)
+# ---------------------------------------------------------------------------
+def depth_for_dim(d):
+    """How deep to push HH_* by dimension (memory- and time-aware on a small host)."""
+    if d <= 6:
+        return 20
+    if d <= 9:
+        return 16
+    if d <= 12:
+        return 12
+    return 9
+
+
+def max_term_dim_for_dim(d):
+    # cap on m^2 * r_n (the k-dimension of a single resolution term)
+    if d <= 9:
+        return 9000
+    if d <= 12:
+        return 13000
+    return 18000
+
+
+def han_verdict(seq):
+    """Classify an HH_* sequence (char-0 proxy) for the Han question.
+
+    Returns a ``(verdict, growth)`` pair.  ``verdict`` is one of:
+      'empty'             : the sequence is empty (no data);
+      'nonzero-tail'      : HH_n > 0 for the LAST computed n (consistent with Han);
+      'COUNTEREXAMPLE?'   : HH_n = 0 for the last computed n -- homology appears to
+                            vanish in high degree, the shape a Han counterexample
+                            would take.
+    ``growth`` is the tail descriptor:
+      'growing'           : >= 6 terms and the last term exceeds the term four back;
+      'bounded'           : otherwise (eventually constant / periodic / too short);
+      '?'                 : only for the empty sequence."""
+    if not seq:
+        return "empty", "?"
+    verdict = "COUNTEREXAMPLE?" if seq[-1] == 0 else "nonzero-tail"
+    # growth: the last term still rising above the term four back
+    growth = "growing" if (len(seq) >= 6 and seq[-1] > seq[max(0, len(seq) - 4)]) else "bounded"
+    return verdict, growth
+
+
+# ---------------------------------------------------------------------------
+# open-zoo -> spec adapter -- ported verbatim from hanlab.cluster.make_shards (MIT)
+# ---------------------------------------------------------------------------
+def _reduction_system_args(entry):
+    """Catalog entry -> the ``reduction_system`` builder's args.
+
+    Matches ``builders._reduction_system(ngen, rules, name[, arrows, vertices])``;
+    legacy (local) entries keep the 3-arg shape byte-for-byte (spec back-compat,
+    same law as ``max_transient_bytes``).  If the builder's arg shape ever changes,
+    this is the only place to touch."""
+    args = [entry["ngen"], entry["rules"], entry["name"]]
+    if "arrows" in entry:
+        args += [entry["arrows"], entry["vertices"]]
+    return args
+
+
+def open_zoo_to_specs(catalog, primes=(PRIME,), max_dim=None, min_dim=None, limit=None,
+                      max_transient_bytes=None):
+    """Convert open-zoo catalog entries to ``reduction_system`` specs, using the same
+    depth/budget policy as the scan_open helpers (so a cluster sweep matches the local one).
+
+    ``min_dim``/``max_dim`` keep only algebras with min_dim <= catalog dim <= max_dim (a
+    dim band -- the cheap-first curriculum); ``limit`` caps the number of specs (after
+    filtering).  ``max_transient_bytes`` (bytes; None = off) is baked into each spec as the
+    per-worker peak-memory budget for the minimal-resolution radK transient, so the spec
+    list stays a pure function of its inputs (sharded == serial).  When None the key is
+    omitted, so existing specs/records are byte-unchanged (back-compat)."""
+    specs = []
+    for e in catalog:
+        d = e["dim"]
+        if max_dim is not None and d > max_dim:
+            continue
+        if min_dim is not None and d < min_dim:
+            continue
+        spec = {
+            "builder": "reduction_system",
+            "args": _reduction_system_args(e),
+            "N": depth_for_dim(d),
+            "primes": list(primes),
+            "max_term_dim": max_term_dim_for_dim(d),
+        }
+        if max_transient_bytes is not None:
+            spec["max_transient_bytes"] = int(max_transient_bytes)
+        specs.append(spec)
+        if limit is not None and len(specs) >= limit:
+            break
+    return specs
+
+
+# ---------------------------------------------------------------------------
+# The pure unit of work
+# ---------------------------------------------------------------------------
+def analyze(spec):
+    """Pure function spec -> record.  Deterministic; safe to run in any process.
+
+    spec: {"builder": str, "args": list, "N": int, "primes": list[int] (optional)}.
+    The "reduction_system" builder routes to the open-zone minimal-resolution path
+    (HH_* only, no cohomology); every other builder takes the structural fast-engine
+    path (HH_* and HH^* over GF(p))."""
+    if spec["builder"] == "reduction_system":
+        return _analyze_open(spec)
+    from quiverlab.engine.scan3 import complexity_of
+
+    primes = tuple(spec.get("primes", (PRIME, 2, 3)))
+    N = spec["N"]
+    builder = spec["builder"]
+    args = list(spec.get("args", []))
+    # rebuild the family over each prime field; the fast engine computes exact F_p HH
+    algs = {p: BUILDERS[builder](*args, field=GF(p)) for p in primes}
+    alg0 = algs[primes[0]]
+    name = spec.get("name") or getattr(alg0, "zoo_name", None) or f"{builder}{tuple(args)}"
+    hh = {p: list(map(int, algs[p].hochschild_homology(N, engine="auto").dims))
+          for p in primes}
+    hc = {p: list(map(int, algs[p].hochschild_cohomology(N, engine="auto").dims))
+          for p in primes}
+    cx_h = complexity_of(hh[primes[0]])
+    cx_c = complexity_of(hc[primes[0]])
+    hseq = hh[primes[0]]                          # char-0 proxy drives the flags
+    return {
+        "name": name,
+        "builder": builder,
+        "args": args,
+        "dim": int(alg0.dim),
+        "N": N,
+        # every quiverlab family is associative by construction (validated at build)
+        "associative": True,
+        "HH_homology": {str(p): hh[p] for p in primes},
+        "HH_cohomology": {str(p): hc[p] for p in primes},
+        "cx_homology": cx_h,
+        "cx_cohomology": cx_c,
+        "asymmetric": bool(cx_h != cx_c),
+        "homology_bounded": bool(cx_h == 0),                # HH_* eventually zero
+        "homology_nonzero_tail": bool(hseq[-1] != 0),       # HH_N != 0
+    }
+
+
+def _analyze_open(spec):
+    """Open-zone record path: HH_* via the minimal A^e-resolution over F_p.
+
+    The minimal engine has no cohomology, so cohomology-side fields are explicit None
+    (`cx_cohomology`, `asymmetric`); the counterexample-query flags are still computed
+    from the HH_* tail so `bounded_homology_candidates` / `by_complexity` work on open
+    rows.  A non-confluent / infinite / unbuildable reduction system yields a JSON error
+    record (never a raise), so a poison spec cannot kill a multiprocessing shard.
+
+    NOTE: this path needs a full open-zone reduction-system -> Algebra build (the Plan-04
+    Chouhy-Solotar backend) to reproduce the golden values on non-monomial systems; the
+    golden port test is skipped until that backend is on the branch."""
+    from quiverlab.engine.adapter import to_engine
+    from quiverlab.engine.resolutions_minimal import (
+        minimal_homology_dims, minimal_resolution)
+    from quiverlab.engine.scan3 import complexity_of
+    from quiverlab.errors import QuiverlabError
+
+    primes = tuple(spec.get("primes", (PRIME,)))
+    args = spec["args"]
+    name = args[2] if len(args) > 2 else "A"
+    rec = {
+        "name": name,
+        "builder": "reduction_system",
+        "args": list(args),
+        "kind": "open",                       # marks the open-zone record family
+        "N": spec.get("N"),                   # carried even on the error path so the
+        # resume-skip / merge-dedup identity (builder, args, N) matches the spec's.
+    }
+    # build (catch bad-input errors -> error record, never crash a worker)
+    try:
+        A = BUILDERS["reduction_system"](*args, field=GF(PRIME))
+    except (QuiverlabError, ValueError) as e:
+        rec["error"] = f"{type(e).__name__}: {e}"
+        rec["associative"] = False            # an unbuildable system is not an algebra
+        return rec
+
+    dim = int(A.dim)
+    N = int(spec.get("N", depth_for_dim(dim)))
+    budget = int(spec.get("max_term_dim", max_term_dim_for_dim(dim)))
+    # Peak-memory guard (bytes; None = off): bounds the dense radK transient so a high-dim
+    # build truncates gracefully instead of OOM-killing the worker.
+    mtb = spec.get("max_transient_bytes")
+    mtb = int(mtb) if mtb is not None else None
+    rec["dim"] = dim
+    rec["N"] = N
+    rec["max_term_dim"] = budget
+    rec["max_transient_bytes"] = mtb
+    rec["associative"] = True                 # validated at build
+
+    # unit-adaptation (b_0 = 1_A) is a LOCAL-algebra convention; on multi-vertex
+    # algebras it destroys the path-type basis the minimal engine's radical
+    # identification needs (the Plan-13 nilpotency guard would refuse) -- pass
+    # those through on their path basis unchanged (Plan 18)
+    E = to_engine(A if len(A.quiver.vertices) > 1 else A.unit_adapted())
+    hh = minimal_homology_dims(E, N, primes=primes, max_term_dim=budget,
+                               max_transient_bytes=mtb)
+    rks, _cols, _eng, trunc = minimal_resolution(E, N, PRIME, max_term_dim=budget,
+                                                 max_transient_bytes=mtb)
+    hseq = hh[PRIME]                          # char-0 proxy drives the verdict/flags
+    verdict, growth = han_verdict(hseq)
+
+    rec["HH_homology"] = {str(p): list(map(int, hh[p])) for p in primes}
+    rec["resolution_ranks"] = [int(rks.get(n, 0)) for n in range(0, N + 2)]
+    rec["depth_reached"] = len(hseq) - 1
+    rec["truncated_at"] = trunc               # None or int (JSON null / int)
+    rec["han_verdict"] = verdict
+    rec["growth"] = growth
+    # cohomology side does not exist on this engine -> explicit None (not a misleading 0)
+    rec["cx_cohomology"] = None
+    rec["asymmetric"] = None
+    # counterexample-query flags from the HH_* tail (keep the structural queries working)
+    rec["cx_homology"] = complexity_of(hseq)
+    rec["homology_bounded"] = bool(rec["cx_homology"] == 0)
+    rec["homology_nonzero_tail"] = bool(hseq[-1] != 0) if hseq else False
+    return rec
+
+
+def run_scan(specs, n_workers=1):
+    """Run `analyze` over a list of specs.  n_workers>1 uses a multiprocessing Pool.
+
+    Returns the list of records in the same order as `specs` (deterministic).
+    Default single-worker: the Pool is imported/created only when n_workers > 1
+    (guarded -- no process fan-out on a small host)."""
+    if n_workers <= 1:
+        return [analyze(s) for s in specs]
+    from multiprocessing import Pool
+    with Pool(processes=n_workers) as pool:
+        return pool.map(analyze, specs)

quiverlab/citations/__init__.py

@@ -0,0 +1,5 @@
+"""quiverlab citations registry (spec §3.9)."""
+from quiverlab.citations.registry import (  # noqa: F401
+    REGISTRY, Reference, reference, bibtex, all_keys, references_bib_path,
+)
+from quiverlab.citations.bibliography import bibliography, Bibliography  # noqa: F401

quiverlab/citations/bibliography.py

@@ -0,0 +1,125 @@
+"""Grouped, annotated, ITERABLE bibliography (spec §3.9). Plan 09's
+references.entry_view() iterates bibliography() and reads e.key / e.formatted /
+e.doi / e.arxiv / e.topic / e.annotation off each entry -- those attribute names
+are the frozen contract. `formatted`, `doi`, and `arxiv` are built from
+references.bib; `topic` is mapped from the registry `kind`; annotations come from
+the registry."""
+import re
+from dataclasses import dataclass
+
+from quiverlab.citations.registry import (
+    REGISTRY, bibtex as _bibtex, reference, references_bib_path,
+)
+
+# topic = the /literature grouping label; mapped from the registry kind.
+_KIND_TOPIC = {"algorithm": "Algorithms", "family": "Families",
+               "field": "Finite fields", "foundation": "Foundations"}
+_TOPIC_ORDER = ("Algorithms", "Families", "Finite fields", "Foundations")
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One bibliography row. Attribute names match Plan 09's entry_view() reads."""
+    key: str            # the registry key -- matches table.references / A.citations()
+    bibtex_key: str
+    formatted: str      # human citation string built from references.bib
+    doi: str | None
+    arxiv: str | None
+    topic: str          # mapped from kind
+    annotation: str
+
+
+def _bib_fields(bibtex_key: str) -> dict:
+    """Pull author/title/journal/year/volume/pages/doi/note from one .bib entry."""
+    text = references_bib_path().read_text(encoding="utf-8")
+    m = re.search(r"@\w+\{" + re.escape(bibtex_key) + r",(.*?\n)\}", text, re.S)
+    body = m.group(1) if m else ""
+    out = {}
+    for fm in re.finditer(r"(\w+)\s*=\s*\{(.*?)\}(?=,\s*\n|\s*\n\})", body, re.S):
+        out[fm.group(1).lower()] = re.sub(r"\s+", " ", fm.group(2)).strip()
+    return out
+
+
+def _clean(s: str) -> str:
+    return (s.replace("{", "").replace("}", "").replace("\\", "")
+             .replace("--", "-").replace("~", " ").strip())
+
+
+def _format(bibtex_key: str, f: dict) -> str:
+    authors = _clean(f.get("author", "")).replace(" and ", "; ")
+    year = f.get("year", "")
+    title = _clean(f.get("title", bibtex_key))
+    venue = _clean(f.get("journal") or f.get("booktitle") or f.get("publisher") or "")
+    vol = f.get("volume", "")
+    pages = _clean(f.get("pages", ""))
+    bits = [b for b in [f"{authors} ({year})." if authors else "", f"{title}.",
+                        f"{venue} {vol}".strip() + (f", {pages}" if pages else "") + "."
+                        if venue else ""] if b]
+    return " ".join(bits)
+
+
+def _arxiv_of(f: dict) -> str | None:
+    m = re.search(r"arXiv:([\w./-]+)", f.get("note", "") + " " + f.get("eprint", ""))
+    return m.group(1) if m else None
+
+
+def _entry(key: str) -> Entry:
+    r = REGISTRY[key]
+    f = _bib_fields(r.bibtex_key)
+    return Entry(key=key, bibtex_key=r.bibtex_key, formatted=_format(r.bibtex_key, f),
+                 doi=f.get("doi"), arxiv=_arxiv_of(f),
+                 topic=_KIND_TOPIC.get(r.kind, "Other"), annotation=r.annotation)
+
+
+@dataclass(frozen=True)
+class Bibliography:
+    keys: tuple
+    _entries: tuple
+
+    def __iter__(self):
+        return iter(self._entries)             # Plan 09 consumes this
+
+    @property
+    def groups(self) -> dict:
+        g = {}
+        for e in self._entries:
+            g.setdefault(e.topic, []).append(e)
+        return g
+
+    def bibtex(self) -> str:
+        out, seen = [], set()
+        for k in self.keys:
+            bk = REGISTRY[k].bibtex_key
+            if bk not in seen:
+                seen.add(bk)
+                out.append(_bibtex(k))
+        return "\n\n".join(out) + ("\n" if out else "")
+
+    def to_dict(self) -> dict:
+        return {"keys": list(self.keys),
+                "groups": {t: [e.__dict__ for e in es] for t, es in self.groups.items()}}
+
+    def __str__(self) -> str:
+        lines = []
+        for t in _TOPIC_ORDER:
+            es = self.groups.get(t)
+            if not es:
+                continue
+            lines.append(f"## {t}")
+            for e in es:
+                lines.append(f"  [{e.key}] {e.formatted}")
+                lines.append(f"      {e.annotation}")
+            lines.append("")
+        return "\n".join(lines).rstrip() + "\n"
+
+
+def bibliography(keys=None, grouped=True, annotated=True) -> Bibliography:
+    if keys is None:
+        keys = list(REGISTRY)
+    seen, ordered = set(), []
+    for k in keys:
+        reference(k)                      # loud on unknown
+        if k not in seen:
+            seen.add(k)
+            ordered.append(k)
+    return Bibliography(tuple(ordered), tuple(_entry(k) for k in ordered))