hypermind 2.4.0__tar.gz → 2.4.1__tar.gz

{hypermind-2.4.0 → hypermind-2.4.1}/.github/workflows/release.yml

@@ -40,6 +40,9 @@ jobs:
     name: test (py${{ matrix.python }})
     needs: guard-source-branch
     runs-on: ubuntu-latest
+    # A wedged self-hosted runner would otherwise sit on the 360-min default
+    # (observed 2026-08-24: run tests step stalled 24+ min vs ~6 min baseline).
+    timeout-minutes: 25
     strategy:
       fail-fast: false
       matrix:
@@ -59,6 +62,7 @@ jobs:
   build:
     name: build sdist + wheel
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: test
     outputs:
       hashes: ${{ steps.hash.outputs.hashes }}
@@ -159,6 +163,7 @@ jobs:
   publish-pypi:
     name: publish → PyPI
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
     environment:
@@ -232,6 +237,7 @@ jobs:
   docker:
     name: docker — hub.docker.com/openworkbench/hypermind
     runs-on: ubuntu-latest
+    timeout-minutes: 45  # multi-arch (amd64+arm64) QEMU build; observed ~95s warm, ~15 min cold
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
     permissions:

{hypermind-2.4.0 → hypermind-2.4.1}/CHANGELOG.md

@@ -14,6 +14,50 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
+(nothing yet)
+
+## [2.4.1] — 2026-08-24
+
+### Fixed
+- **Relata read path broken by relata-db ≥2026-08-10 builds (`AS OF CURRENT`).**
+  Every `RelataBackend` read (`load_claims`, `load_claim_stubs`, head-seq,
+  recent-findings) carried a bi-temporal `AS OF CURRENT` clause; on the
+  2026-08-10 server build that filter reduces `HmClaim` queries to the
+  table's internal sentinel rows only (live-validated 2026-08-24: 1
+  sentinel row returned vs 411 claims without the clause), so every
+  Relata-backed read — restore-on-startup, `hmctl show --relata-url`,
+  replay — silently came back empty. A plain `SELECT` is already
+  current-state semantics and works on every build; the clause is removed
+  from all four read sites.
+- **`from_relata()` node labels.** DB-sourced canvases showed bare hex ids;
+  the per-author label is now harvested from the GAP-R10 claim stubs
+  alongside unit/role.
+- **`hmctl show` community/unit mapping (org structure was invisible).**
+  Communities detected from cite/vouch affinity were labelled anonymously
+  ("community 1/2/…") and org structure (e.g. a university template's
+  departments) leaked into the *topic* filter instead. The canvas now:
+  - names each community after its members' dominant `unit` (nodes carry
+    `community`; `meta.communities` lists them; clusters with no unit info
+    keep the stable generic label);
+  - ships a dedicated **community filter** (`#hm-community`) across the
+    agents / conversation / claims panes, and the cluster legend uses the
+    real names;
+  - `from_relata()` harvests per-author unit/role from the GAP-R10 claim
+    stub columns, so DB-sourced canvases carry attribution without a live
+    world;
+  - `RelataBackend.append_claim()` derives `label`/`unit`/`role` from the
+    claim payload when the caller passes none (GAP-R10 parity for the bare
+    agent path — `world.persist_claim` → `append_claim(stmt)` used to
+    persist empty attribution for every plain `publish_claim()`).
+  Regression-pinned in `tests/viz/` (naming, fallback label, from_relata
+  enrichment, filter markup).
+- **`HyperMindAgent.cite()` default-uncertainty crash.** The no-`uncertainty=`
+  branch built `Uncertainty(alpha=9.0, beta=1.0)` against the current
+  `(kind, params)` constructor, so every cite without an explicit
+  `Uncertainty` raised `TypeError`. Found live during tenant-onboarding
+  validation (2026-08-24); regression-pinned in
+  `tests/test_agent_cite_default.py`.
+
 ## [2.4.0] — 2026-08-24
 
 ### Added

{hypermind-2.4.0 → hypermind-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypermind
-Version: 2.4.0
+Version: 2.4.1
 Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
 Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
 Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs

{hypermind-2.4.0 → hypermind-2.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "2.4.0"
+version = "2.4.1"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.12,<3.15"

{hypermind-2.4.0 → hypermind-2.4.1}/src/hypermind/agent.py

@@ -3173,7 +3173,7 @@ class HyperMindAgent:
         # Publish the citation record so it is sealed and auditable.
         from hypermind.uncertainty import Uncertainty as _Uncertainty
 
-        _unc = uncertainty if uncertainty is not None else _Uncertainty(alpha=9.0, beta=1.0)
+        _unc = uncertainty if uncertainty is not None else _Uncertainty("beta", (9.0, 1.0))
         return await self.publish_claim(
             {
                 "claim_type": "cite",

{hypermind-2.4.0 → hypermind-2.4.1}/src/hypermind/storage/relata.py

@@ -140,7 +140,12 @@ class RelataBackend:
         # Initialise next_seq from the high-water mark so append order survives
         # restart. Relata's SQL subset rejects COALESCE(MAX(...)); use ORDER BY
         # DESC LIMIT 1 instead (verified against the live server).
-        rows = self._rows("SELECT seq FROM HmClaim AS OF CURRENT ORDER BY seq DESC LIMIT 1")
+        # NOTE: deliberately no `AS OF CURRENT` — the relata-db 2026-08-10
+        # build's bi-temporal filter reduces `SELECT * … AS OF CURRENT` to
+        # the table's internal sentinel rows only (live-validated 2026-08-24:
+        # 1 sentinel row vs 411 claims without the clause). A plain SELECT is
+        # already current-state semantics, and works on every build.
+        rows = self._rows("SELECT seq FROM HmClaim ORDER BY seq DESC LIMIT 1")
         # Sentinel rows share the table and carry no seq (see load_claims).
         self._seq = (int(rows[0]["seq"]) + 1) if rows and rows[0].get("seq") is not None else 1
 
@@ -203,6 +208,14 @@ class RelataBackend:
             confidence = float(user.get("confidence", 0.7))
             if topic is None:
                 topic = user.get("topic") or None
+            # GAP-R10 parity for the bare agent path: ``world.persist_claim``
+            # calls ``append_claim(stmt)`` with no attribution kwargs, which
+            # left label/unit/role empty for every plain ``publish_claim()``.
+            # Derive from the payload exactly like text/topic so DB-backed
+            # canvases can name communities by unit.
+            label = label or str(user.get("label", "") or "")
+            unit = unit or str(user.get("unit", "") or "")
+            role = role or str(user.get("role", "") or "")
             source_url = str(user.get("source_url", "") or "")
             source_type = str(user.get("source_type", "") or "")
             arxiv_id = str(user.get("arxiv_id", "") or "")
@@ -321,7 +334,7 @@ class RelataBackend:
         self.flush_claims()
         # RELATA-005: include namespace column so cross-sim claim bleed is filtered.
         rows = self._rows(
-            f"SELECT wire_b64, namespace FROM HmClaim AS OF CURRENT ORDER BY created_ms DESC LIMIT {int(max(1, limit))}"
+            f"SELECT wire_b64, namespace FROM HmClaim ORDER BY created_ms DESC LIMIT {int(max(1, limit))}"
         )
         _ns = self._ns
         out: list[tuple[str, str]] = []
@@ -348,7 +361,7 @@ class RelataBackend:
         # SELECT * — some Relata builds intermittently return a tiny subset of
         # rows for multi-column projections while SELECT * returns them all
         # (observed live 2026-08-24); read all columns and project here.
-        rows = self._rows("SELECT * FROM HmClaim AS OF CURRENT ORDER BY seq ASC")
+        rows = self._rows("SELECT * FROM HmClaim ORDER BY seq ASC")
         out: list[SignedStatement] = []
         for r in rows:
             wire = r.get("wire_b64")
@@ -367,7 +380,7 @@ class RelataBackend:
         survives restarts without a full CBOR decode.
         """
         self.flush_claims()
-        rows = self._rows("SELECT * FROM HmClaim AS OF CURRENT ORDER BY seq DESC")
+        rows = self._rows("SELECT * FROM HmClaim ORDER BY seq DESC")
         return [
             {
                 "kid_hex": r.get("id", ""),

{hypermind-2.4.0 → hypermind-2.4.1}/src/hypermind/viz/canvas_html.py

@@ -300,6 +300,7 @@ def render_canvas_html(
   <div class="filters" id="hm-filters">
     <input id="hm-search" type="search" placeholder="Search agents, findings, reasons…" autocomplete="off">
     <select id="hm-topic" aria-label="filter by topic"><option value="">all topics</option></select>
+    <select id="hm-community" aria-label="filter by community"><option value="">all communities</option></select>
     <label class="toggle"><input type="checkbox" checked data-edge="cites"><span class="key cites"></span>cites</label>
     <label class="toggle"><input type="checkbox" checked data-edge="vouches"><span class="key vouches"></span>vouches</label>
     <label class="toggle"><input type="checkbox" checked data-edge="disputes"><span class="key disputes"></span>disputes</label>
@@ -538,7 +539,7 @@ _JS = """
   function edgeColor(t) { return (EDGE_COLOR[t] || OTHER)[dark ? 1 : 0]; }
 
   // ---- state ----------------------------------------------------------
-  var state = { tab: 'graph', search: '', topic: '', edgeTypes: { cites: true, vouches: true, disputes: true }, cursor: 0, sort: { key: null, dir: 1 } };
+  var state = { tab: 'graph', search: '', topic: '', community: '', edgeTypes: { cites: true, vouches: true, disputes: true }, cursor: 0, sort: { key: null, dir: 1 } };
 
   var nodeById = {};
   var clusterColor = {}, clusterLabel = {};
@@ -553,9 +554,17 @@ _JS = """
     var sizes = {};
     nodes.forEach(function (n) { var c = n.cluster == null ? 0 : n.cluster; sizes[c] = (sizes[c] || 0) + 1; });
     var order = Object.keys(sizes).sort(function (a, b) { return sizes[b] - sizes[a] || (+a) - (+b); });
+    // Prefer the backend-provided community name (dominant unit of the
+    // cluster's members — e.g. a university template's departments); fall
+    // back to the anonymous slot label when the source has no unit info.
+    var nameByCluster = {};
+    nodes.forEach(function (n) {
+      var c = String(n.cluster == null ? 0 : n.cluster);
+      if (n.community && !(c in nameByCluster)) nameByCluster[c] = n.community;
+    });
     clusterLabel = {};
     order.forEach(function (c, i) {
-      clusterLabel[c] = i < CATEGORICAL.length ? 'community ' + (+c + 1) : 'other';
+      clusterLabel[c] = i < CATEGORICAL.length ? (nameByCluster[c] || 'community ' + (+c + 1)) : 'other';
     });
     return sizes;
   }
@@ -582,6 +591,19 @@ _JS = """
     });
     sel.value = (prevTopic === '' || topics[prevTopic]) ? prevTopic : '';
     state.topic = sel.value;
+    // Community filter options rebuilt the same way; a selection survives
+    // only if the community still exists.
+    var csel = document.getElementById('hm-community');
+    var prevCommunity = csel.value;
+    var communities = {};
+    nodes.forEach(function (n) { if (n.community) communities[n.community] = 1; });
+    csel.textContent = '';
+    var call = el('option'); call.value = ''; call.textContent = 'all communities'; csel.appendChild(call);
+    Object.keys(communities).sort().forEach(function (c) {
+      var o = el('option'); o.value = c; o.textContent = c; csel.appendChild(o);
+    });
+    csel.value = (prevCommunity === '' || communities[prevCommunity]) ? prevCommunity : '';
+    state.community = csel.value;
     // Tab badges + header stat tiles follow the new data.
     var counts = { agents: nodes.length, conversation: events.length, claims: claims.length, disputes: disputes.length, research: hypotheses.length + evidence.length };
     document.querySelectorAll('#hm-tabs .tab').forEach(function (b) {
@@ -610,6 +632,12 @@ _JS = """
   document.getElementById('hm-topic').addEventListener('change', function () {
     var sel = document.getElementById('hm-topic'); state.topic = sel.value; renderAll();
   });
+  document.getElementById('hm-community').addEventListener('change', function () {
+    var csel = document.getElementById('hm-community'); state.community = csel.value; renderAll();
+  });
+  // Community of an event/claim/dispute actor: falls back to '' (matches
+  // no community filter) when the actor isn't a known node.
+  function communityOf(id) { var n = nodeById[id]; return n ? (n.community || '') : ''; }
   function n_topic_scan() {
     var ts = [];
     claims.forEach(function (c) { if (c.topic) ts.push(c.topic); });
@@ -937,6 +965,7 @@ _JS = """
     var rows = nodes.filter(function (n) {
       if (visible && !visible[n.id]) return false;
       if (state.topic && !(n.reputation || {})[state.topic]) return false;
+      if (state.community && (n.community || '') !== state.community) return false;
       return true;
     });
     if (!rows.length) { host.appendChild(el('div', 'empty', 'no agents match the current filters')); return; }
@@ -1014,6 +1043,7 @@ _JS = """
     var visible = matchesSearch();
     var rows = events.filter(function (ev) {
       if (state.topic && ev.topic !== state.topic) return false;
+      if (state.community && communityOf(ev.actor) !== state.community) return false;
       if (visible && !(ev.actor && visible[ev.actor]) && !(ev.target && visible[ev.target])) return false;
       if (state.search) {
         var hay = ((ev.text || '') + ' ' + (ev.detail || '') + ' ' + (ev.topic || '')).toLowerCase();
@@ -1064,6 +1094,7 @@ _JS = """
     host.textContent = '';
     var rows = claims.filter(function (c) {
       if (state.topic && c.topic !== state.topic) return false;
+      if (state.community && communityOf(c.author) !== state.community) return false;
       if (state.search) {
         var hay = ((c.finding || '') + ' ' + (c.claim_type || '') + ' ' + (c.author || '') + ' ' + labelOf(c.author)).toLowerCase();
         if (hay.indexOf(state.search) === -1) return false;

{hypermind-2.4.0 → hypermind-2.4.1}/src/hypermind/viz/snapshot.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import base64
 import json
+from collections import Counter
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -116,6 +117,23 @@ def _finish(
     clusters = _detect_communities(nodes, edges)
     for node_id, cluster_id in clusters.items():
         nodes[node_id]["cluster"] = cluster_id
+    # Name each community by the dominant `unit` of its members so org
+    # structure (e.g. a university template's departments) is legible
+    # instead of an anonymous "community N". Interaction-derived clusters
+    # with no unit info keep the generic label.
+    unit_tally: dict[int, Counter[str]] = {}
+    for node in nodes.values():
+        unit = node.get("unit")
+        if unit:
+            unit_tally.setdefault(node["cluster"], Counter())[unit] += 1
+    community_names: dict[int, str] = {}
+    for cluster_id in set(clusters.values()):
+        tally = unit_tally.get(cluster_id)
+        community_names[cluster_id] = (
+            tally.most_common(1)[0][0] if tally else f"community {cluster_id + 1}"
+        )
+    for node in nodes.values():
+        node["community"] = community_names[node["cluster"]]
     node_list = sorted(nodes.values(), key=lambda n: n["id"])
     return NetworkSnapshot(
         nodes=node_list,
@@ -131,6 +149,7 @@ def _finish(
             "n_edges": len(edges),
             "n_events": len(events),
             "n_clusters": len(set(clusters.values())),
+            "communities": sorted(set(community_names.values())),
             "source": source,
         },
     )
@@ -438,11 +457,40 @@ def from_relata(url: str, *, namespace: str, token: str | None = None) -> Networ
             {"kid": kid.hex(), "topic": topic, "alpha": alpha, "beta": beta}
             for kid, topic, alpha, beta, _last_update_ms in backend.load_reputation()
         ]
+        stubs = backend.load_claim_stubs()
     finally:
         backend.close()
 
+    # Per-author attribution from the GAP-R10 claim columns: the majority
+    # unit/role/label across each author's claims. from_live_world gets this
+    # from the live agent objects; a Relata deployment only has what was
+    # persisted on claims — without this, DB-sourced canvases have no unit
+    # info (communities fall back to anonymous labels) and every node shows
+    # a bare hex id instead of a human label.
+    unit_tally: dict[str, Counter[str]] = {}
+    role_tally: dict[str, Counter[str]] = {}
+    label_tally: dict[str, Counter[str]] = {}
+    for s in stubs:
+        author = s.get("author_hex") or ""
+        if s.get("unit"):
+            unit_tally.setdefault(author, Counter())[s["unit"]] += 1
+        if s.get("role"):
+            role_tally.setdefault(author, Counter())[s["role"]] += 1
+        if s.get("label"):
+            label_tally.setdefault(author, Counter())[s["label"]] += 1
+    agents_meta = {
+        author: {
+            "role": role_tally[author].most_common(1)[0][0] if author in role_tally else None,
+            "unit": unit_tally[author].most_common(1)[0][0] if author in unit_tally else None,
+            "label": label_tally[author].most_common(1)[0][0] if author in label_tally else None,
+            "namespace": namespace,
+            "rooms": [],
+        }
+        for author in set(role_tally) | set(unit_tally) | set(label_tally)
+    }
+
     return _build_from_native(
-        agents_meta={},
+        agents_meta=agents_meta,
         sealed=sealed,
         disputes=disputes,
         rep_rows=rep_rows,

hypermind-2.4.1/tests/test_agent_cite_default.py

@@ -0,0 +1,24 @@
+"""Regression: `cite()` with no explicit uncertainty must not crash.
+
+The default branch once built `Uncertainty(alpha=9.0, beta=1.0)` against a
+constructor that takes `(kind, params)` — found live while onboarding a tenant
+(2026-08-24). Every other path passed an explicit Uncertainty, so only the
+default was broken.
+"""
+
+from hypermind import HyperMindAgent, Uncertainty
+
+
+async def test_cite_without_explicit_uncertainty_uses_beta_default() -> None:
+    async with HyperMindAgent.sandbox(room="cite-default") as alice:
+        first = await alice.publish_claim(
+            {"finding": "ground truth for the citation"},
+            uncertainty=Uncertainty.beta(7, 3),
+        )
+        second = await alice.publish_claim(
+            {"finding": "the citing claim"},
+            uncertainty=Uncertainty.beta(5, 5),
+        )
+        # No `uncertainty=` — exercises the default-branch constructor.
+        cite_kid = await alice.cite(second, first)
+        assert cite_kid.hex() != first.hex()

{hypermind-2.4.0 → hypermind-2.4.1}/tests/viz/test_canvas_html.py

@@ -276,6 +276,28 @@ def test_render_has_dashboard_tabs_and_filter_row():
     )
 
 
+def test_render_has_community_filter_and_named_communities():
+    # Communities are named per-cluster (majority unit) and the dashboard has
+    # a dedicated filter for them — org structure like a university's
+    # departments must be selectable, not buried in the topic dropdown.
+    snap = _snapshot()
+    snap.nodes[0]["community"] = "physics"
+    snap.nodes[1]["community"] = "physics"
+    snap.nodes[2]["community"] = "biology"
+    snap.meta["communities"] = ["biology", "physics"]
+    html = render_canvas_html(snap, title="T")
+    assert '<select id="hm-community"' in html
+    assert 'aria-label="filter by community"' in html
+    # the client-side helper that resolves a node's community exists
+    assert "function communityOf(" in html
+    # named communities ride in the payload so applyColors() can label the
+    # cluster legend with real names
+    payload = _embedded_payload(html)
+    n = {x["id"]: x for x in payload["nodes"]}
+    assert n["a"]["community"] == "physics"
+    assert n["c"]["community"] == "biology"
+
+
 def test_render_never_injects_untrusted_text_into_markup():
     # Findings/reasons are untrusted (LLM/tool output). They may only reach
     # the page as JSON inside the inert data block (script-context escaped)

{hypermind-2.4.0 → hypermind-2.4.1}/tests/viz/test_relata.py

@@ -74,6 +74,10 @@ class _FakeClient:
         if "COUNT(*)" in sql:
             table = sql.split("FROM ")[1].split()[0]
             return _FakeResult([{"n": len(objs.get(table, {}))}])
+        if sql.startswith("SELECT * FROM HmClaim ORDER BY seq DESC"):
+            # load_claim_stubs(): full rows, newest first
+            rows = sorted(objs.get("HmClaim", {}).values(), key=lambda f: f["seq"], reverse=True)
+            return _FakeResult(rows)
         if "ORDER BY seq DESC" in sql:
             seqs = [f["seq"] for f in objs.get("HmClaim", {}).values()]
             return _FakeResult([{"seq": max(seqs)}] if seqs else [])
@@ -196,3 +200,95 @@ def test_from_relata_reads_claims_disputes_and_reputation(monkeypatch):
     # in-memory only) — a Relata-sourced snapshot must not fabricate any.
     assert not [e for e in snap.edges if e["type"] == "vouches"]
     assert snap.meta["source"] == "relata"
+
+
+def test_from_relata_derives_unit_and_names_communities_from_claim_stubs(monkeypatch):
+    # GAP-R10 attribution: the bare agent path persists claims whose payload
+    # carries label/unit/role. from_relata() must harvest the stub columns to
+    # give DB-sourced canvases per-agent unit/role — and _finish() must name
+    # each community after its dominant unit instead of "community N".
+    import cbor2
+
+    store = _FakeStore()
+    kps = [Keypair.generate() for _ in range(4)]
+
+    def _claim(kp, *, logical_ms, unit, finding):
+        payload = cbor2.dumps(
+            {
+                "claim_type": "eval_result",
+                "topic": "research",
+                "payload": {
+                    "finding": finding,
+                    "unit": unit,
+                    "role": "scout",
+                    "label": f"{unit}-scout",
+                },
+            },
+            canonical=True,
+        )
+        return _sign_claim(kp, logical_ms=logical_ms, payload=payload)
+
+    physics_a = _claim(kps[0], logical_ms=1, unit="physics", finding="entropy wins")
+    physics_b = _claim(kps[1], logical_ms=2, unit="physics", finding="entropy loses")
+    biology_c = _claim(kps[2], logical_ms=3, unit="biology", finding="cells divide")
+    biology_d = _claim(kps[3], logical_ms=4, unit="biology", finding="cells merge")
+    cite_biology = _sign_claim(
+        kps[3],
+        logical_ms=5,
+        payload=cbor2.dumps(
+            {
+                "claim_type": "custom",
+                "topic": "research",
+                "payload": {
+                    "claim_type": "cite",
+                    "target_kid": biology_c.kid.hex(),
+                    "unit": "biology",
+                },
+            },
+            canonical=True,
+        ),
+    )
+    cite_physics = _sign_claim(
+        kps[1],
+        logical_ms=6,
+        payload=cbor2.dumps(
+            {
+                "claim_type": "custom",
+                "topic": "research",
+                "payload": {
+                    "claim_type": "cite",
+                    "target_kid": physics_a.kid.hex(),
+                    "unit": "physics",
+                },
+            },
+            canonical=True,
+        ),
+    )
+
+    seed_backend = RelataBackend(
+        "http://fake", namespace_id="research", client_factory=_factory(store)
+    )
+    seed_backend.open()
+    for stmt in (physics_a, physics_b, biology_c, biology_d, cite_biology, cite_physics):
+        seed_backend.append_claim(stmt)
+    seed_backend.close()
+
+    real_init = RelataBackend.__init__
+
+    def _patched_init(self, base_url, **kwargs):
+        kwargs["client_factory"] = _factory(store)
+        real_init(self, base_url, **kwargs)
+
+    monkeypatch.setattr(RelataBackend, "__init__", _patched_init)
+
+    snap = from_relata("http://fake", namespace="research", token="tok")
+
+    by_id = {n["id"]: n for n in snap.nodes}
+    assert by_id[kps[0].kid.hex()]["unit"] == "physics"
+    assert by_id[kps[2].kid.hex()]["unit"] == "biology"
+    assert by_id[kps[0].kid.hex()]["role"] == "scout"
+    assert by_id[kps[0].kid.hex()]["community"] == "physics"
+    assert by_id[kps[2].kid.hex()]["community"] == "biology"
+    assert set(snap.meta["communities"]) == {"physics", "biology"}
+    # human labels ride along too — the agents table shouldn't show bare hex
+    assert by_id[kps[0].kid.hex()]["label"] not in ("", None, kps[0].kid.hex())

{hypermind-2.4.0 → hypermind-2.4.1}/tests/viz/test_snapshot.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import base64
+import json
 from types import SimpleNamespace
 
 import pytest
@@ -152,6 +153,118 @@ def test_from_jsonl_builds_expected_node_and_edge_shape(tmp_path):
     assert snap.meta["n_nodes"] == 2
 
 
+def test_from_jsonl_names_communities_by_majority_unit(tmp_path):
+    # Two rings (physics, biology) connected only by a dispute: each cluster
+    # must be named after its members' dominant `unit` — org structure (e.g.
+    # a university template's departments) has to be legible on the canvas,
+    # not an anonymous "community N".
+    records = [
+        {
+            "record": "reputation",
+            "label": "p1",
+            "unit": "physics",
+            "role": "scout",
+            "reputation": 0.7,
+        },
+        {
+            "record": "reputation",
+            "label": "p2",
+            "unit": "physics",
+            "role": "sceptic",
+            "reputation": 0.6,
+        },
+        {
+            "record": "claim",
+            "kid": "kp1",
+            "label": "p1",
+            "round": 1,
+            "unit": "physics",
+            "finding": "entropy wins",
+            "confidence": 0.8,
+        },
+        {
+            "record": "claim",
+            "kid": "kp2",
+            "label": "p2",
+            "round": 1,
+            "unit": "physics",
+            "finding": "entropy loses",
+            "confidence": 0.4,
+        },
+        {"record": "citation", "edge": ["p2", "kp1"]},
+        {
+            "record": "reputation",
+            "label": "b1",
+            "unit": "biology",
+            "role": "scout",
+            "reputation": 0.5,
+        },
+        {
+            "record": "reputation",
+            "label": "b2",
+            "unit": "biology",
+            "role": "oracle",
+            "reputation": 0.5,
+        },
+        {
+            "record": "claim",
+            "kid": "kb1",
+            "label": "b1",
+            "round": 1,
+            "unit": "biology",
+            "finding": "cells divide",
+        },
+        {
+            "record": "claim",
+            "kid": "kb2",
+            "label": "b2",
+            "round": 1,
+            "unit": "biology",
+            "finding": "cells merge",
+        },
+        {"record": "citation", "edge": ["b2", "kb1"]},
+        # cross-ring tension only — must NOT merge the rings into one community
+        {
+            "record": "dispute",
+            "target": "kb1",
+            "target_by": "b1",
+            "disputer": "p1",
+            "unit": "biology",
+            "round": 2,
+        },
+    ]
+    path = tmp_path / "rings.jsonl"
+    path.write_text("\n".join(json.dumps(r) for r in records), encoding="utf-8")
+
+    snap = from_jsonl(str(path))
+    by_id = {n["id"]: n for n in snap.nodes}
+    assert by_id["p1"]["community"] == "physics"
+    assert by_id["p2"]["community"] == "physics"
+    assert by_id["b1"]["community"] == "biology"
+    assert by_id["b2"]["community"] == "biology"
+    assert set(snap.meta["communities"]) == {"physics", "biology"}
+    # the unit itself stays on the node for the agents drawer
+    assert by_id["p1"]["unit"] == "physics"
+
+
+def test_from_jsonl_cluster_without_units_keeps_generic_name(tmp_path):
+    # Interaction-derived cluster with no unit info anywhere: the fallback
+    # label must stay stable ("community N"), never crash or go empty.
+    records = [
+        {"record": "reputation", "label": "x", "unit": None, "role": None, "reputation": 0.5},
+        {"record": "reputation", "label": "y", "unit": None, "role": None, "reputation": 0.5},
+        {"record": "claim", "kid": "kx", "label": "x", "round": 1, "finding": "fx"},
+        {"record": "citation", "edge": ["y", "kx"]},
+    ]
+    path = tmp_path / "plain.jsonl"
+    path.write_text("\n".join(json.dumps(r) for r in records), encoding="utf-8")
+
+    snap = from_jsonl(str(path))
+    communities = {n["community"] for n in snap.nodes}
+    assert communities == {"community 1"}
+    assert snap.meta["communities"] == ["community 1"]
+
+
 def test_from_jsonl_resolves_identity_via_wire_bytes(tmp_path):
     # Real records carry `wire_b64` — the label ("alice") and the true kid
     # hex are different identity spaces that must be joined through it.