graphify-mesh 0.0.22__py3-none-any.whl

graphify_mesh/server/http_app.py

@@ -0,0 +1,367 @@
+"""Streamable-HTTP transport: one shared daemon for every local agent.
+
+Stateless by design — `cwd` travels in each tool call, so there is no
+per-session state worth keeping, and a client that disappears leaves nothing
+behind. The bearer token is mandatory: unlike the unix socket this replaces,
+a loopback TCP port is reachable by every local user and process, and what it
+serves is the merged graph of every repository in registry.json.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hmac
+import json
+import logging
+from collections import deque
+from collections.abc import AsyncIterator, Callable
+
+import anyio
+from anyio import to_thread
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.routing import Route
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from graphify_mesh.server.config import ServerConfig, is_loopback_bind
+from graphify_mesh.server.frames import (
+    MAX_MESSAGE_BYTES,
+    PARSE_ERROR,
+    envelope_error,
+    error_frame_text,
+    frame_id,
+)
+from graphify_mesh.server.sdk_app import build_sdk_server
+from graphify_mesh.server.server import GraphifyMeshServer
+
+log = logging.getLogger("graphify_mesh.server.http_app")
+
+# A bound exists because a request being read holds up to `MAX_MESSAGE_BYTES`
+# of body in this one shared process, so unbounded concurrent reads make
+# inbound memory unbounded too. It bounds body buffering specifically, and it
+# QUEUES rather than rejecting: making a local agent's request wait a few
+# milliseconds is better than failing it. Not uvicorn's `limit_concurrency`,
+# which answers 503 once the number of open CONNECTIONS reaches the limit —
+# on a daemon serving many long-lived keep-alive clients that rejects the
+# 33rd client with nothing in flight at all.
+BODY_BUFFER_SLOTS = 8
+
+# Bodies above this size are parsed in a worker thread: a multi-megabyte
+# `json.loads` on the event loop stalls every other client of this shared
+# daemon for its whole duration. Below it the thread hop costs more than the
+# parse, so small frames stay inline.
+INLINE_PARSE_MAX_BYTES = 64 * 1024
+
+
+def _security_settings(config: ServerConfig) -> TransportSecuritySettings:
+    """DNS-rebinding protection, decided by the same rule
+    `config.is_loopback_bind` applies to the bind permission. A non-loopback
+    bind, a wildcard or a concrete interface address alike, both of which
+    require `--allow-public-bind`, is reachable under many names, so it
+    accepts any Host and leaves the bearer token as the gate, like the upstream
+    `graphify` server (`serve.py:_build_http_app`). A loopback bind restricts
+    Host to that address plus the localhost aliases, each with and without
+    the port."""
+    if not is_loopback_bind(config.http_host):
+        return TransportSecuritySettings(enable_dns_rebinding_protection=False)
+    allowed = {config.http_host, "localhost", "127.0.0.1"}
+    allowed |= {f"{host}:{config.http_port}" for host in list(allowed)}
+    return TransportSecuritySettings(allowed_hosts=sorted(allowed))
+
+
+class _MCPASGIApp:
+    """Raw-ASGI wrapper around the streamable-HTTP session manager, so
+    Starlette treats this as the ASGI app for the mount path directly with
+    no request/response wrapping that would break the streaming path."""
+
+    def __init__(self, manager: StreamableHTTPSessionManager) -> None:
+        self._manager = manager
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        await self._manager.handle_request(scope, receive, send)
+
+
+class _TokenAuthMiddleware:
+    """Mandatory bearer-token gate, ahead of the session manager.
+
+    Raw ASGI, not Starlette's `BaseHTTPMiddleware`: that middleware buffers
+    the response and breaks the Streamable HTTP stream. Never logs the
+    token, the Authorization header, or the request body — a rejection logs
+    only the remote address and the fact of rejection.
+    """
+
+    def __init__(self, app: ASGIApp, token: str) -> None:
+        self.app = app
+        self._expected = token.encode("utf-8")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # The raw list, not a dict: dict() keeps only the last value of a
+        # repeated header, so a request carrying both a wrong and a right
+        # `authorization` would be accepted or rejected on header order
+        # alone. More than one of them is ambiguous, so it is rejected
+        # before any comparison runs.
+        supplied = [
+            value for name, value in (scope.get("headers") or []) if name == b"authorization"
+        ]
+        provided: bytes | None = None
+        if len(supplied) == 1:
+            scheme, _, candidate = supplied[0].partition(b" ")
+            if scheme.lower() == b"bearer" and candidate:
+                provided = candidate.strip()
+
+        if provided is None or not hmac.compare_digest(provided, self._expected):
+            client = scope.get("client")
+            remote = client[0] if client else "unknown"
+            log.warning("rejected unauthorized request from %s", remote)
+            body = b'{"error": "unauthorized"}'
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [
+                        (b"content-type", b"application/json"),
+                        (b"content-length", str(len(body)).encode("ascii")),
+                    ],
+                }
+            )
+            await send({"type": "http.response.body", "body": body})
+            return
+
+        await self.app(scope, receive, send)
+
+
+async def _send_json(send: Send, status: int, body: bytes) -> None:
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(body)).encode("ascii")),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body})
+
+
+class _FrameGuardMiddleware:
+    """Size cap and envelope check for POST bodies, between the token gate
+    and the session manager.
+
+    Two things the SDK does differently from `stdio_guard`, both visible to a
+    client that got past the token gate:
+
+    * its body limit is its own default rather than this package's number,
+      so the two transports stated different caps;
+    * its parse and envelope errors carry `str(JSONDecodeError)` or
+      `str(ValidationError)` — validation details and excerpts of the input —
+      straight to the client, where stdio answers generically.
+
+    So the body is read here, under `MAX_MESSAGE_BYTES` counted on bytes
+    actually received (a chunked client has no `Content-Length` to check),
+    checked with the same `frames.envelope_error` stdio uses, and replayed
+    downstream untouched when it is well-formed. The detail goes to the log;
+    the client gets a fixed message.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+        # One semaphore per app, so a test app and the daemon never share one.
+        self._slots = anyio.Semaphore(BODY_BUFFER_SLOTS)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope.get("method") != "POST":
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope.get("headers") or [])
+        declared = headers.get(b"content-length")
+        if declared is not None and declared.isdigit() and int(declared) > MAX_MESSAGE_BYTES:
+            # Nothing is buffered on this path, so it takes no slot.
+            await self._too_large(scope, send)
+            return
+
+        await self._slots.acquire()
+        released = False
+
+        def release_slot() -> None:
+            # The slot covers the span where THIS middleware holds body
+            # bytes, and nothing more: it is handed back as soon as the body
+            # reaches the app below, never held across the downstream call,
+            # which would cap real request concurrency at `BODY_BUFFER_SLOTS`
+            # instead of bounding memory.
+            nonlocal released
+            if not released:
+                released = True
+                self._slots.release()
+
+        try:
+            await self._guarded(scope, receive, send, release_slot)
+        finally:
+            release_slot()
+
+    async def _guarded(
+        self, scope: Scope, receive: Receive, send: Send, release_slot: Callable[[], None]
+    ) -> None:
+        body = bytearray()
+        body_complete = False
+        trailing: Message | None = None
+        while True:
+            message = await receive()
+            if message["type"] != "http.request":
+                trailing = dict(message)
+                break
+            chunk = message.get("body", b"")
+            if len(body) + len(chunk) > MAX_MESSAGE_BYTES:
+                # Answer now; the rest of the body is never read, so an
+                # over-limit client cannot make this process buffer it.
+                await self._too_large(scope, send)
+                return
+            body.extend(chunk)
+            if not message.get("more_body", False):
+                body_complete = True
+                break
+
+        try:
+            if len(body) > INLINE_PARSE_MAX_BYTES:
+                # `json.loads` accepts the bytearray directly, so the thread
+                # gets the same single buffer, not a copy of it.
+                parsed = await to_thread.run_sync(json.loads, body)
+            else:
+                parsed = json.loads(body)
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            log.warning("rejected unparseable request body from %s: %s", _remote(scope), exc)
+            await _send_json(send, 400, error_frame_text(*PARSE_ERROR).encode("utf-8"))
+            return
+
+        coded = envelope_error(parsed)
+        if coded is not None:
+            log.warning(
+                "rejected malformed JSON-RPC frame from %s (code %d)", _remote(scope), coded[0]
+            )
+            frame = error_frame_text(*coded, frame_id(parsed))
+            await _send_json(send, 400, frame.encode("utf-8"))
+            return
+
+        # Both references are dropped before dispatching downstream: the
+        # parsed object would otherwise stay live for the whole call (several
+        # times the byte size of the body, as Python objects), and `body` is
+        # handed to `_replayed_receive` as-is rather than copied, so exactly
+        # one buffer of these bytes exists here at any moment.
+        del parsed
+        replay = _replayed_receive(body, body_complete, trailing, receive, release_slot)
+        del body
+        await self.app(scope, replay, send)
+
+    async def _too_large(self, scope: Scope, send: Send) -> None:
+        log.warning(
+            "rejected oversized request body from %s (> %d bytes)",
+            _remote(scope),
+            MAX_MESSAGE_BYTES,
+        )
+        await _send_json(send, 413, b'{"error": "request body too large"}')
+
+
+def _remote(scope: Scope) -> str:
+    client = scope.get("client")
+    return client[0] if client else "unknown"
+
+
+def _replayed_receive(
+    body: bytearray,
+    body_complete: bool,
+    trailing: Message | None,
+    receive: Receive,
+    on_handoff: Callable[[], None],
+) -> Receive:
+    """Hands the already-read body to the app below exactly once, then falls
+    back to the real `receive` (for the disconnect message).
+
+    `on_handoff` runs when the body message has been delivered: at that point
+    the app below owns these bytes and this layer holds none, which is what
+    the body-buffer slot was reserving. The buffer is passed through rather
+    than copied to `bytes`; the only consumer is the SDK's
+    `RequestBodyLimitMiddleware`, which extends its own bytearray from it and
+    never requires an immutable `bytes`.
+    """
+    queued: deque[Message] = deque(
+        [{"type": "http.request", "body": body, "more_body": not body_complete}]
+    )
+    if trailing is not None:
+        queued.append(trailing)
+
+    async def replay() -> Message:
+        if queued:
+            message = queued.popleft()
+            if message["type"] == "http.request":
+                on_handoff()
+            return message
+        return await receive()
+
+    return replay
+
+
+def build_http_app(mesh: GraphifyMeshServer, config: ServerConfig) -> Starlette:
+    """The ASGI app for the shared streamable-HTTP daemon. No server
+    started — for in-process tests and for `serve_http` to run under
+    uvicorn."""
+    if not config.http_token:
+        raise ValueError("http transport requires config.http_token")
+
+    sdk = build_sdk_server(mesh)
+    security = _security_settings(config)
+
+    # Stateless: no sessions, no SSE, no session reaper. `cwd` travels in
+    # each tool call instead.
+    manager = StreamableHTTPSessionManager(
+        app=sdk,
+        json_response=True,
+        stateless=True,
+        security_settings=security,
+        # The same number stdio caps a line at. Left to its default, the
+        # HTTP bound would be the SDK's, which is both a different number
+        # and one that can change between SDK releases. `session_idle_timeout`
+        # is deliberately NOT passed: the SDK documents it as unused in
+        # stateless mode, and a parameter this adapter does not need is one
+        # more thing an SDK release can move.
+        max_request_body_size=MAX_MESSAGE_BYTES,
+    )
+
+    @contextlib.asynccontextmanager
+    async def lifespan(_app: Starlette) -> AsyncIterator[None]:
+        # The session manager owns an anyio task group that must wrap the
+        # whole server lifetime, so enter it here rather than per-request.
+        async with manager.run():
+            yield
+
+    return Starlette(
+        routes=[Route(config.http_path, endpoint=_MCPASGIApp(manager))],
+        # Order matters: the token gate stays outermost, so an
+        # unauthenticated request is answered before this process reads,
+        # buffers or parses a single byte of its body.
+        middleware=[
+            Middleware(_TokenAuthMiddleware, token=config.http_token),
+            Middleware(_FrameGuardMiddleware),
+        ],
+        lifespan=lifespan,
+    )
+
+
+def serve_http(mesh: GraphifyMeshServer, config: ServerConfig) -> None:
+    """Blocking streamable-HTTP transport on the configured host and port."""
+    import uvicorn
+
+    app = build_http_app(mesh, config)
+    log.info(
+        "graphify-mesh http daemon: host=%s port=%s path=%s token required",
+        config.http_host,
+        config.http_port,
+        config.http_path,
+    )
+    uvicorn.run(app, host=config.http_host, port=config.http_port)

graphify_mesh/server/lexical_read.py

@@ -0,0 +1,208 @@
+"""Version-aware read-path for the `lexical-index.json` bundle.
+
+The sync pipeline writes exactly one schema version (the current
+`LEXICAL_SCHEMA_VERSION` in sync/lexical_index.py), but the server must keep
+serving whatever the CURRENT published generation contains — publish can lag
+behind a deploy (e.g. shrink-guard blocking), so the reader understands the
+previous on-disk shape too. All schema branching lives HERE; retrieval.py and
+similar.py consume shape-agnostic tuples.
+
+v2 shape: postings `term -> [[repo, key, field], ...]`,
+          alias_exact `alias -> [[repo, key], ...]`,
+          doc_freq stored under `doc_freq.global`.
+v3 shape: `documents` table (list index = doc id), `fields` table
+          (list index = field id), postings `term -> [packed_int, ...]`
+          with `packed = (doc_id << FIELD_PACK_BITS) | field_index`,
+          alias_exact `alias -> [doc_id, ...]`, doc_freq NOT stored
+          (derived: distinct doc ids in the term's postings).
+
+Malformed entries are skipped, never raised: a partially-corrupt index
+degrades retrieval quality, it must not take the server down.
+"""
+
+from __future__ import annotations
+
+import bisect
+from collections.abc import Iterable
+
+SCHEMA_V2 = 2
+SCHEMA_V3 = 3
+# Low bits reserved for the field index inside a packed v3 posting entry.
+FIELD_PACK_BITS = 2
+_FIELD_MASK = (1 << FIELD_PACK_BITS) - 1
+
+_V2_POSTING_LEN = 3
+_V2_ALIAS_LEN = 2
+
+
+def _get_dict(container: object, key: str) -> dict:
+    """Fetch `container[key]` and guarantee a dict comes back, no matter how
+    malformed `container` or the value at `key` is. Container-level
+    hardening: `container` itself may be a non-dict scalar (e.g. the whole
+    `lexical` artifact got corrupted into a string), or the value stored at
+    `key` may be the wrong shape (a list, an int, ...) — either way this
+    degrades to an empty dict rather than raising."""
+    if not isinstance(container, dict):
+        return {}
+    value = container.get(key, {})
+    if not isinstance(value, dict):
+        return {}
+    return value
+
+
+def _get_list(container: object, key: str) -> list:
+    """Same contract as `_get_dict`, but for list-shaped members
+    (`documents`, `fields`)."""
+    if not isinstance(container, dict):
+        return []
+    value = container.get(key, [])
+    if not isinstance(value, list):
+        return []
+    return value
+
+
+def _get_entries(container: dict, key: str) -> list:
+    """Fetch `container[key]` and guarantee a list comes back. Used for a
+    single term's/alias's posting list, which must be iterable — a
+    corrupted artifact may store a scalar (e.g. an int) there instead."""
+    value = container.get(key, [])
+    if not isinstance(value, list):
+        return []
+    return value
+
+
+def _schema(lexical: object) -> int:
+    if not isinstance(lexical, dict):
+        return SCHEMA_V2
+    version = lexical.get("schema_version")
+    if isinstance(version, int) and not isinstance(version, bool):
+        return version
+    return SCHEMA_V2
+
+
+def _doc_ref(lexical: object, doc_id: int) -> tuple[str, str] | None:
+    documents = _get_list(lexical, "documents")
+    if not isinstance(doc_id, int) or isinstance(doc_id, bool):
+        return None
+    if doc_id < 0 or doc_id >= len(documents):
+        return None
+    entry = documents[doc_id]
+    if not isinstance(entry, list) or len(entry) != 2:
+        return None
+    return (entry[0], entry[1])
+
+
+def alias_refs(lexical: object, norm_alias: str) -> list[tuple[str, str]]:
+    alias_exact = _get_dict(lexical, "alias_exact")
+    entries = _get_entries(alias_exact, norm_alias)
+    if _schema(lexical) == SCHEMA_V2:
+        return [(e[0], e[1]) for e in entries if isinstance(e, list) and len(e) == _V2_ALIAS_LEN]
+    refs: list[tuple[str, str]] = []
+    for doc_id in entries:
+        ref = _doc_ref(lexical, doc_id)
+        if ref is None:
+            continue
+        refs.append(ref)
+    return refs
+
+
+def term_postings(lexical: object, term: str) -> list[tuple[str, str, str]]:
+    postings = _get_dict(lexical, "postings")
+    entries = _get_entries(postings, term)
+    if _schema(lexical) == SCHEMA_V2:
+        return [
+            (e[0], e[1], e[2]) for e in entries if isinstance(e, list) and len(e) == _V2_POSTING_LEN
+        ]
+    fields = _get_list(lexical, "fields")
+    triples: list[tuple[str, str, str]] = []
+    for packed in entries:
+        if not isinstance(packed, int) or isinstance(packed, bool):
+            continue
+        ref = _doc_ref(lexical, packed >> FIELD_PACK_BITS)
+        if ref is None:
+            continue
+        field_index = packed & _FIELD_MASK
+        if field_index >= len(fields):
+            continue
+        triples.append((ref[0], ref[1], fields[field_index]))
+    return triples
+
+
+def term_doc_freq(lexical: object, term: str) -> int:
+    postings = _get_dict(lexical, "postings")
+    if _schema(lexical) == SCHEMA_V2:
+        doc_freq = _get_dict(lexical, "doc_freq")
+        global_freq = _get_dict(doc_freq, "global")
+        stored = global_freq.get(term)
+        if isinstance(stored, int) and not isinstance(stored, bool):
+            return stored
+        return len(_get_entries(postings, term))
+    entries = _get_entries(postings, term)
+    distinct = {
+        packed >> FIELD_PACK_BITS
+        for packed in entries
+        if isinstance(packed, int) and not isinstance(packed, bool)
+    }
+    return len(distinct)
+
+
+def doc_ids_by_key(lexical: object) -> dict[str, list[int]] | None:
+    """v3 only (`None` for v2): key -> doc ids from the `documents` table.
+    A list, not one id: two nodes sharing repo, source file and label share a
+    key but are separate documents. Malformed entries are skipped exactly as
+    `_doc_ref` skips them."""
+    if _schema(lexical) == SCHEMA_V2:
+        return None
+    by_key: dict[str, list[int]] = {}
+    for doc_id, entry in enumerate(_get_list(lexical, "documents")):
+        if not isinstance(entry, list) or len(entry) != 2 or not isinstance(entry[1], str):
+            continue
+        by_key.setdefault(entry[1], []).append(doc_id)
+    return by_key
+
+
+def _is_packed(entry: object) -> bool:
+    return isinstance(entry, int) and not isinstance(entry, bool)
+
+
+def term_doc_hits(lexical: object, term: str, doc_ids: Iterable[int]) -> set[int]:
+    """v3 only: the subset of `doc_ids` that `term` has a posting for, with
+    the same entry validity `term_postings` applies (int entry, known field).
+    Binary search per doc id over the sorted posting list; a list whose
+    entries do not compare (corrupt, mixed types) falls back to a scan."""
+    entries = _get_entries(_get_dict(lexical, "postings"), term)
+    field_count = len(_get_list(lexical, "fields"))
+    wanted = set(doc_ids)
+    try:
+        return {d for d in wanted if _bisect_hit(entries, d, field_count)}
+    except TypeError:
+        hits: set[int] = set()
+        for packed in entries:
+            if _is_packed(packed) and (packed & _FIELD_MASK) < field_count:
+                doc_id = packed >> FIELD_PACK_BITS
+                if doc_id in wanted:
+                    hits.add(doc_id)
+        return hits
+
+
+def _bisect_hit(entries: list, doc_id: int, field_count: int) -> bool:
+    index = bisect.bisect_left(entries, doc_id << FIELD_PACK_BITS)
+    while index < len(entries):
+        packed = entries[index]
+        index += 1
+        if not _is_packed(packed):
+            continue
+        if packed >> FIELD_PACK_BITS != doc_id:
+            return False
+        if (packed & _FIELD_MASK) < field_count:
+            return True
+    return False
+
+
+def document_count(lexical: object) -> int:
+    if not isinstance(lexical, dict):
+        return 0
+    count = lexical.get("document_count")
+    if isinstance(count, int) and not isinstance(count, bool):
+        return count
+    return len(_get_list(lexical, "documents"))

graphify_mesh/server/project_map.py

@@ -0,0 +1,92 @@
+"""`project_map(repo)` tool (WS5 tool 4): a structural overview of one
+registered repo in the CURRENT generation — node count, a trimmed
+community_name breakdown, and the top hub nodes by structural degree. Purely
+read-only over the already-loaded `Generation`; `Generation.nodes_by_repo` / `.adjacency`
+already cover everything this needs, so no separate index is built here.
+
+Fails closed like everything else in this package: an unresolvable repo
+(unknown to the registry, or simply absent from the current generation —
+e.g. registered but never synced yet) returns `resolved=False` with a
+`degraded` reason, never a silently-empty-looking success.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from graphify_mesh.server import ranking
+from graphify_mesh.server.store import Generation
+
+# How many top-degree nodes to surface per repo. Kept small and named
+# (project style: no magic numbers) — this is an orientation summary, not a
+# full node dump.
+TOP_HUBS_LIMIT = 15
+
+# `community_breakdown` keeps only communities of at least this size, and at
+# most this many of them (largest first). Community labels are LLM-named
+# clusters: an unreliable orientation hint, not a module map. Singletons were
+# most of the list — about 4 KB of noise per call on cem.hub's 128
+# communities. `communities_total` / `communities_omitted` report the cut.
+COMMUNITY_MIN_SIZE = 2
+COMMUNITY_BREAKDOWN_LIMIT = 25
+
+
+@dataclass
+class ProjectMapResult:
+    resolved: bool
+    repo: str = ""
+    node_count: int = 0
+    community_breakdown: dict = field(default_factory=dict)
+    communities_total: int = 0  # every community in the repo, "unassigned" included
+    communities_omitted: int = 0  # communities_total minus len(community_breakdown)
+    top_hubs: list = field(default_factory=list)  # [{key, label, degree, source_file, is_hub}]
+    degraded: list = field(default_factory=list)
+
+
+def project_map(repo_id: str, generation: Generation) -> ProjectMapResult:
+    node_ids = generation.nodes_by_repo.get(repo_id)
+    if not node_ids:
+        return ProjectMapResult(
+            resolved=False, repo=repo_id, degraded=["repo_not_in_current_generation"]
+        )
+
+    community_breakdown: dict[str, int] = {}
+    scored: list[tuple[int, str, str]] = []  # (degree, key, node_id) — key used as tie-break
+    for node_id in node_ids:
+        node = generation.node_by_id.get(node_id, {})
+        community = node.get("community_name") or "unassigned"
+        community_breakdown[community] = community_breakdown.get(community, 0) + 1
+        key = generation.key_by_node_id.get(node_id)
+        if key is None:
+            continue
+        scored.append((generation.degree(node_id), key, node_id))
+
+    # Deterministic: degree desc, then key asc (never dict/set iteration order).
+    scored.sort(key=lambda t: (-t[0], t[1]))
+    top_hubs = []
+    for degree, key, node_id in scored[:TOP_HUBS_LIMIT]:
+        node = generation.node_by_id.get(node_id, {})
+        top_hubs.append(
+            {
+                "key": key,
+                "label": node.get("label", ""),
+                "degree": degree,
+                "source_file": node.get("source_file", ""),
+                "is_hub": degree > ranking.HUB_DEGREE_THRESHOLD,
+            }
+        )
+
+    # Deterministic: size desc, then name asc; then the size floor and limit.
+    ranked_communities = sorted(community_breakdown.items(), key=lambda kv: (-kv[1], kv[0]))
+    kept = [kv for kv in ranked_communities if kv[1] >= COMMUNITY_MIN_SIZE]
+    kept = kept[:COMMUNITY_BREAKDOWN_LIMIT]
+
+    return ProjectMapResult(
+        resolved=True,
+        repo=repo_id,
+        node_count=len(node_ids),
+        community_breakdown=dict(kept),
+        communities_total=len(ranked_communities),
+        communities_omitted=len(ranked_communities) - len(kept),
+        top_hubs=top_hubs,
+    )