hyperweave 0.2.6__tar.gz → 0.2.8__tar.gz

{hyperweave-0.2.6 → hyperweave-0.2.8}/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to HyperWeave are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.8] - 2026-04-20
+
+### Fixed
+
+- **Star history charts now render readably on large repositories.** Previously, repos with more than ~40,000 stars produced a flat-then-vertical "hockey stick" because GitHub's stargazer REST endpoint hard-caps deep pagination, so the only data reachable was a small cluster of early-history stars followed by a single jump to today. Star history now sources from GitHub's GraphQL API and adapts its sampling window to the repo: small repos continue to get full lifetime views, large repos get a detailed recent-growth curve similar to the one star-history.com shows.
+- **Star-count milestone labels no longer stack on top of each other.** When sampled points clustered temporally, the milestone labels (`500`, `1K`, `5K`, `10K`, ...) would render in a single illegible pile on top of the crossing point. Milestones now maintain a minimum 40-pixel horizontal gap; any labels that would overlap with an already-placed one are dropped in favor of the first (lowest-threshold) milestone in the cluster.
+
+### Changed
+
+- **All chart rendering now flows through template partials.** The chart engine's remaining rendering paths — axes, gridlines, polyline, area fill, milestones, and the empty-state overlay — joined the marker layer in Jinja. The engine module returns structured Python data; Jinja partials under `templates/components/` produce the final SVG. No visual change; output is byte-identical for the shipped genomes on unchanged inputs.
+
+### Added
+
+- **`fetch_graphql` connector primitive.** New async helper in the connector layer that handles POST with JSON bodies, GitHub bearer-token rotation, circuit-breaker coordination, and SSRF validation — mirroring the existing `fetch_json` contract. This unlocks future migration of the stats card's six REST sub-fetches to a single GraphQL call, and keeps a single canonical place for authenticated-POST plumbing.
+
+### Dev
+
+- GraphQL stargazer pipeline is covered by unit tests for the primary path, REST fallback on failure, no-token skip, mega-repo window cap, small-repo history exhaustion, downsampling correctness, and current-UTC now-point stamping.
+
+## [0.2.7] - 2026-04-20
+
+### Fixed
+
+- **Star history charts now end at the current date.** On very large repositories (40k+ stars), GitHub caps stargazer pagination at roughly the first 40,000 stars, so the latest sample pulled from the API was often years old and the polyline terminated in the past. The chart now always appends a final data point stamped at the current time, while still reporting the real total star count. Small repos are unaffected.
+- **Session receipt labels are honest again.** The "N corrections" line previously counted every user turn — any pushback, redirect, or elaboration — and rendered them next to tool-failure marks (`✗N`) on the token treemap, which created the impression that the two numbers should reconcile. They're now split into "N user turns" and "N tool errors", with tool-error counts tinted red to match the cell marks. A new legend — `✗N = failed tool calls` — appears above the token map so the red marks are self-explanatory.
+- **Session receipt hero no longer misreports the dominant work phase.** The hero badge previously showed the label of the first detected stage, even when that stage lasted two minutes and a later stage dominated the session. It now uses the stage with the largest share of tool calls, and falls back to `MIXED` when no single stage exceeds 20%.
+- **Rhythm bars stop overflowing their track on long sessions.** On sessions with many stages (~30+), the rightmost rhythm bar on the receipt could render hundreds of pixels past the track's right edge. Receipt and rhythm-strip now share a single layout routine with a proper gap budget and a post-hoc rescale, so bars always fit the track regardless of stage count.
+- **Rhythm bars encode time, not tool-call share.** When the telemetry contract carries start and end timestamps per stage, bar widths are now proportional to stage duration, so the time-axis labels (`0m · 104m · 209m`) actually correspond to bar positions. Bar heights are now uniform; the previous height scaling was effectively noise because most bars hit the minimum-height floor.
+- **Live badges now recognize `building` as a state.** A badge with `value="building"` (or `"rebuilding"` / `"build"`) now renders as the building state instead of falling through to the default `active`. Longer phrases containing the word "build" are not affected — only those three exact tokens.
+- **Deploying `HW_GITHUB_TOKENS` no longer crashes the app.** A vestigial `github_tokens` field on the settings schema was trying to parse the environment variable as JSON on startup, so setting the plain comma-separated secret that the token-rotation code actually expects caused a 500. The field has been removed; the connector reads the secret directly, and plain comma-separated deployments now work as documented.
+
+### Added
+
+- **`hw_discover` advertises the `stats`, `chart`, and `timeline` routes.** MCP clients calling `hw_discover(what="url_grammar")` now receive URL patterns, example URLs, and method hints for the three routes that shipped in v0.2.0 but were missing from discovery.
+
+### Changed
+
+- **Chart markers render through template partials.** Marker shapes (rect, circle, diamond, and their endpoint variants) now live as Jinja partials under `templates/components/chart-markers/`, matching how the rest of the rendering pipeline handles SVG. No visual change; output is byte-identical for the shipped genomes.
+
+### Dev
+
+- GitHub token pool rotation is now covered by unit tests (`HW_GITHUB_TOKENS` comma-separated list, `GITHUB_TOKEN` single-token fallback, whitespace tolerance, empty-env behavior).
+
 ## [0.2.6] - 2026-04-19
 
 ### Added

{hyperweave-0.2.6 → hyperweave-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperweave
-Version: 0.2.6
+Version: 0.2.8
 Summary: Headless visual output layer for AI agents. One API call → self-contained SVG.
 Project-URL: Repository, https://github.com/InnerAura/hyperweave
 Project-URL: Issues, https://github.com/InnerAura/hyperweave/issues

{hyperweave-0.2.6 → hyperweave-0.2.8}/src/hyperweave/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.6'
-__version_tuple__ = version_tuple = (0, 2, 6)
+__version__ = version = '0.2.8'
+__version_tuple__ = version_tuple = (0, 2, 8)
 
 __commit_id__ = commit_id = None

{hyperweave-0.2.6 → hyperweave-0.2.8}/src/hyperweave/compose/context.py

@@ -337,12 +337,16 @@ def _ctx_chart(spec: ComposeSpec, resolved: ResolvedArtifact, css: dict[str, str
     ctx["chart_viewport_w"] = 0
     ctx["chart_viewport_h"] = 0
     ctx["chart_defs"] = ""
-    ctx["chart_axes"] = ""
-    ctx["chart_gridlines"] = ""
-    ctx["chart_area"] = ""
-    ctx["chart_polyline"] = ""
-    ctx["chart_markers"] = ""
-    ctx["chart_milestones"] = ""
+    # Post-v0.2.8: axes / gridlines / milestones / markers all return structured
+    # lists; polyline / area / empty_state are dicts or None so templates can
+    # use ``{% if %}`` to guard includes without a StrictUndefined trap.
+    ctx["chart_axes"] = []
+    ctx["chart_gridlines"] = []
+    ctx["chart_area"] = None
+    ctx["chart_polyline"] = None
+    ctx["chart_markers"] = []
+    ctx["chart_milestones"] = []
+    ctx["chart_empty_state"] = None
     ctx["data_hw_status"] = "fresh"
     ctx.update(resolved.frame_context)
     return ctx
@@ -371,7 +375,7 @@ def _ctx_stats(spec: ComposeSpec, resolved: ResolvedArtifact, css: dict[str, str
     ctx["embedded_chart_defs"] = ""
     ctx["embedded_chart_area"] = ""
     ctx["embedded_chart_polyline"] = ""
-    ctx["embedded_chart_markers"] = ""
+    ctx["embedded_chart_markers"] = []
     ctx.update(resolved.frame_context)
     return ctx
 

{hyperweave-0.2.6 → hyperweave-0.2.8}/src/hyperweave/compose/resolver.py

@@ -6,6 +6,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from hyperweave.compose.rhythm import layout_rhythm_bars
 from hyperweave.core.enums import (
     FrameType,
     GlyphMode,
@@ -1112,7 +1113,7 @@ def resolve_receipt(
     profile_data: dict[str, Any] = tel.get("profile", {})
     tools_raw = tel.get("tools", {})
     stages_raw: list[dict[str, Any]] = tel.get("stages", [])
-    corrections: list[dict[str, Any]] = tel.get("corrections", [])
+    user_events: list[dict[str, Any]] = tel.get("user_events", [])
     agents: list[dict[str, Any]] = tel.get("agents", [])
 
     # ── Normalize tools: contract produces dict keyed by name, templates need list ──
@@ -1122,7 +1123,8 @@ def resolve_receipt(
         tools = list(tools_raw)
 
     # ── Normalize stages: contract produces {label, dominant_class, start, end, tools} ──
-    # Templates need {name, pct, tool_class} with percentage proportions
+    # Templates need {name, pct, tool_class}; start/end are preserved so
+    # :func:`layout_rhythm_bars` can lay out time-proportional x/w.
     total_stage_tools = sum(s.get("tools", 1) for s in stages_raw) or 1
     stages: list[dict[str, Any]] = [
         {
@@ -1130,6 +1132,8 @@ def resolve_receipt(
             "pct": round(s.get("tools", 1) / total_stage_tools * 100),
             "label": s.get("label", ""),
             "tool_class": s.get("dominant_class", "explore"),
+            "start": s.get("start"),
+            "end": s.get("end"),
         }
         for s in stages_raw
     ]
@@ -1161,21 +1165,43 @@ def resolve_receipt(
         "Send": "coordinate",
     }
 
+    # ── Dominant phase (drives hero badge + bottom-right phase label) ──
+    # Using stages[0] was the old bug — for a session where the first 2-minute
+    # stage classified as "validation" but the dominant (45% of tool calls)
+    # was "implementation", the hero badge lied. When no single stage owns
+    # at least 20% of the tool calls, fall back to "MIXED" to avoid
+    # overclaiming a dominant phase that doesn't exist.
+    dominant = max(stages, key=lambda s: s.get("pct", 0)) if stages else None
+    dominant_label = (dominant.get("label") or dominant.get("name") or "") if dominant else ""
+    dominant_pct = dominant.get("pct", 0) if dominant else 0
+
     # ── Hero row ──
     hero_headline = f"{_fmt_tok(total_tok)} tokens billed · ${total_cost:.2f}"
     dur_label = f"{int(duration_m)}m" if duration_m else "—"
     hero_subline = f"{model} · {dur_label} · {calls} calls"
-    hero_profile = stages[0]["label"].upper() if stages else "SESSION"
-    hero_tool_class = stages[0]["tool_class"] if stages else "explore"
-    n_corrections = len(corrections)
+    if not dominant:
+        hero_profile = "SESSION"
+    elif dominant_pct < 20:
+        hero_profile = "MIXED"
+    else:
+        hero_profile = dominant_label.upper()
+    hero_tool_class = dominant["tool_class"] if dominant else "explore"
+    # Split "pushbacks" into distinct signals so the card stops labeling them
+    # as one opaque "N corrections" lie. user_events counts every non-continuation
+    # user turn (corrections + redirects + elaborations); tool errors count
+    # failing/blocked tool calls (the red ✗N cell marks reconcile to this).
+    n_user_turns = len(user_events)
+    n_tool_errors = sum(t.get("errors", 0) + t.get("blocked", 0) for t in tools)
     n_agents = len(agents)
-    hero_right = [
-        f"{_fmt_tok(total_input)} in / {_fmt_tok(total_output)} out",
+    hero_right: list[dict[str, str]] = [
+        {"text": f"{_fmt_tok(total_input)} in / {_fmt_tok(total_output)} out"},
     ]
     if total_cache_read or total_cache_create:
-        hero_right.append(f"{_fmt_tok(total_cache_read)} cached / {_fmt_tok(total_cache_create)} written")
-    if n_corrections:
-        hero_right.append(f"{n_corrections} correction{'s' if n_corrections != 1 else ''}")
+        hero_right.append({"text": f"{_fmt_tok(total_cache_read)} cached / {_fmt_tok(total_cache_create)} written"})
+    if n_user_turns:
+        hero_right.append({"text": f"{n_user_turns} user turn{'s' if n_user_turns != 1 else ''}"})
+    if n_tool_errors:
+        hero_right.append({"text": f"{n_tool_errors} tool errors", "accent": "failing"})
 
     # ── Treemap layout (3-tier, 752px wide, token-proportional) ──
     content_w = 752
@@ -1253,29 +1279,16 @@ def resolve_receipt(
                 )
                 x += min(w, 180) + 4
 
-    # ── Rhythm bars (scale stages to 752px) ──
-    total_stage_pct = sum(s.get("pct", 0) for s in stages) or 100
-    rhythm_bars: list[dict[str, Any]] = []
-    rx = 0
+    # ── Rhythm bars ──
+    # Delegated to the shared helper so receipt + rhythm-strip can't drift.
+    # See src/hyperweave/compose/rhythm.py for the two-pass algorithm.
     bar_area_h = 92
-    for s in stages:
-        pct = s.get("pct", 0)
-        w = max(int(content_w * pct / total_stage_pct), 6)
-        h = max(int(bar_area_h * (pct / 50)), 8)
-        y = bar_area_h - h
-        tc = s.get("tool_class", s.get("name", "explore"))
-        rhythm_bars.append({"x": rx, "y": y, "w": w, "h": h, "tool_class": tc})
-        rx += w + 2
+    rhythm_bars = layout_rhythm_bars(stages, area_w=content_w, area_h=bar_area_h)
 
     # ── Legend entries ──
     used_classes = sorted({c["tool_class"] for c in treemap_cells}) if treemap_cells else ["explore"]
     treemap_legend = [{"tool_class": tc, "label": tc} for tc in used_classes]
 
-    # ── Dominant phase ──
-    dominant = max(stages, key=lambda s: s.get("pct", 0)) if stages else {"name": "", "pct": 0}
-    dominant_label = dominant.get("label", dominant.get("name", ""))
-    dominant_pct = dominant.get("pct", 0)
-
     # ── Metadata band (v0.4): provenance row between rhythm legend and footer ──
     session_id = session.get("id", "")
     session_id_short = session_id[:8].rstrip("-") if session_id else ""
@@ -1307,11 +1320,14 @@ def resolve_receipt(
     metadata_right = " · ".join(metadata_right_parts)
 
     # ── Footer: session stats (left) + brand anchor (right) ──
+    # Same split as hero so nothing in the card claims "corrections" anymore.
     footer_parts = []
-    if n_corrections:
-        footer_parts.append(f"{n_corrections} corrections")
+    if n_user_turns:
+        footer_parts.append(f"{n_user_turns} user turn{'s' if n_user_turns != 1 else ''}")
+    if n_tool_errors:
+        footer_parts.append(f"{n_tool_errors} tool error{'s' if n_tool_errors != 1 else ''}")
     if n_agents:
-        footer_parts.append(f"{n_agents} agents")
+        footer_parts.append(f"{n_agents} agent{'s' if n_agents != 1 else ''}")
     footer_left = " · ".join(footer_parts) if footer_parts else ""
     footer_right = "hyperweave.app"
 
@@ -1325,7 +1341,7 @@ def resolve_receipt(
             "hero_tool_class": hero_tool_class,
             "hero_headline": hero_headline,
             "hero_subline": hero_subline,
-            "hero_right_stats": [{"text": t} for t in hero_right],
+            "hero_right_stats": hero_right,
             "treemap_legend": treemap_legend,
             "treemap_cells": treemap_cells,
             "stage_count": len(stages),
@@ -1368,12 +1384,16 @@ def resolve_rhythm_strip(
         tools = list(tools_raw)
 
     # ── Normalize stages ──
+    # start/end preserved so :func:`layout_rhythm_bars` can lay out
+    # time-proportional widths when the contract carries them.
     total_stage_tools = sum(s.get("tools", 1) for s in stages_raw) or 1
     stages: list[dict[str, Any]] = [
         {
             "name": s.get("dominant_class", s.get("label", "explore")),
             "pct": round(s.get("tools", 1) / total_stage_tools * 100),
             "tool_class": s.get("dominant_class", "explore"),
+            "start": s.get("start"),
+            "end": s.get("end"),
         }
         for s in stages_raw
     ]
@@ -1389,38 +1409,10 @@ def resolve_rhythm_strip(
 
     # Rhythm bars — must match template bar_w = sw - stats_w - right_w - 16.
     # With sw=800, stats_w=180, right_w=120: bar_area_w = 484.
-    # Budget accounts for 2px gaps between bars so many-stage sessions don't
-    # overflow into the right-side loop-status panel.
+    # Delegated to the shared helper — see src/hyperweave/compose/rhythm.py.
     bar_area_w = 484
     bar_area_h = 42
-    gap_px = 2
-    n_stages = len(stages)
-    gap_budget = gap_px * max(n_stages - 1, 0)
-    available_w = max(bar_area_w - gap_budget, bar_area_w // 2)
-    min_bar_w = max(2, available_w // max(n_stages, 1) // 3) if n_stages else 6
-    total_stage_pct = sum(s.get("pct", 0) for s in stages) or 100
-
-    raw_bars: list[dict[str, Any]] = []
-    for s in stages:
-        pct = s.get("pct", 0)
-        w = max(int(available_w * pct / total_stage_pct), min_bar_w)
-        h = max(int(bar_area_h * (pct / 50)), 6)
-        y = bar_area_h - h
-        tc = s.get("tool_class", "explore")
-        raw_bars.append({"w": w, "h": h, "y": y, "tool_class": tc})
-
-    # Post-hoc uniform scale if floor-pressure still exceeds budget
-    raw_total = sum(b["w"] for b in raw_bars)
-    if raw_total > available_w and raw_total > 0:
-        scale = available_w / raw_total
-        for b in raw_bars:
-            b["w"] = max(int(b["w"] * scale), 2)
-
-    rhythm_bars: list[dict[str, Any]] = []
-    rx = 0
-    for b in raw_bars:
-        rhythm_bars.append({"x": rx, "y": b["y"], "w": b["w"], "h": b["h"], "tool_class": b["tool_class"]})
-        rx += b["w"] + gap_px
+    rhythm_bars = layout_rhythm_bars(stages, area_w=bar_area_w, area_h=bar_area_h)
 
     # Velocity estimate
     vel = int(total_tok / max(duration_m, 1)) if duration_m else 0

hyperweave-0.2.8/src/hyperweave/compose/rhythm.py

@@ -0,0 +1,109 @@
+"""Rhythm-bar layout: time-proportional x/w with uniform heights.
+
+Shared between :func:`resolve_receipt` and :func:`resolve_rhythm_strip`
+so the receipt's "79-stage bars overflow the track" bug can't diverge
+from rhythm-strip's correct two-pass algorithm.
+
+Algorithm (two passes):
+    1. Reserve a gap budget up front so ``n_bars x gap_px`` never steals
+       from the width budget. Compute a minimum bar width floor based on
+       ``n_bars`` so each bar is still visible under extreme stage counts.
+    2. Raw widths: time-proportional when every stage carries ISO
+       ``start``/``end`` timestamps (preferred — the time-axis labels
+       then agree with the bar positions); fall back to tool-call-share
+       pct when timestamps are missing (legacy contract).
+    3. Post-hoc uniform rescale if the raw sum still exceeds the gap
+       budget (happens when the min-bar-width floor dominates).
+    4. Emit ``{x, y, w, h, tool_class}`` with ``h = BAR_HEIGHT`` uniform.
+
+Uniform height is intentional. The old resolver's
+``h = max(int(bar_area_h * (pct / 50)), 8)`` made ~76 of 79 bars hit
+the 8px floor, implying a signal dimension the data didn't carry.
+Three channels (time x category x color) is already enough; the
+fourth (height) had no clear semantic and was therefore noise.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+BAR_HEIGHT = 14
+"""Uniform rhythm-bar height. Shared by receipt (area_h=92) and rhythm-strip
+(area_h=42): both align the bars flush to the bottom of their track."""
+
+
+def layout_rhythm_bars(
+    stages: list[dict[str, Any]],
+    area_w: int,
+    area_h: int,
+    gap_px: int = 2,
+) -> list[dict[str, Any]]:
+    """Lay out rhythm bars into a bounded track with a gap budget + rescale.
+
+    Args:
+        stages: Normalized stage dicts. Each MAY carry ``start``/``end``
+            ISO strings for time-proportional layout; otherwise layout
+            falls back to ``pct`` (tool-call share).
+        area_w: Track width in pixels.
+        area_h: Track height in pixels. Used only for ``y`` (bars align
+            bottom-flush); ``h`` is always :data:`BAR_HEIGHT`.
+        gap_px: Inter-bar gap in pixels. Reserved upfront in the budget
+            so many-stage sessions don't overflow into adjacent panels.
+
+    Returns:
+        One dict per stage: ``{x, y, w, h, tool_class}``. Empty list when
+        ``stages`` is empty.
+    """
+    if not stages:
+        return []
+
+    n = len(stages)
+    gap_budget = gap_px * max(n - 1, 0)
+    # Cap the worst case: never give up more than half the track to gaps.
+    available_w = max(area_w - gap_budget, area_w // 2)
+
+    has_timestamps = all(s.get("start") and s.get("end") for s in stages)
+    if has_timestamps:
+        t0 = datetime.fromisoformat(stages[0]["start"])
+        t_end = datetime.fromisoformat(stages[-1]["end"])
+        total_s = max((t_end - t0).total_seconds(), 1.0)
+        raw_w = [
+            max(
+                int(
+                    available_w
+                    * (datetime.fromisoformat(s["end"]) - datetime.fromisoformat(s["start"])).total_seconds()
+                    / total_s
+                ),
+                2,
+            )
+            for s in stages
+        ]
+    else:
+        total_pct = sum(s.get("pct", 0) for s in stages) or 100
+        # Per-bar minimum: 1/3 of the equal-share width so tiny stages
+        # stay visible without swallowing the whole budget.
+        min_bar_w = max(2, available_w // max(n, 1) // 3)
+        raw_w = [max(int(available_w * s.get("pct", 0) / total_pct), min_bar_w) for s in stages]
+
+    # Post-hoc uniform rescale: if the floor pressure drove the sum over budget.
+    raw_total = sum(raw_w)
+    if raw_total > available_w and raw_total > 0:
+        scale = available_w / raw_total
+        raw_w = [max(int(w * scale), 2) for w in raw_w]
+
+    y = area_h - BAR_HEIGHT
+    bars: list[dict[str, Any]] = []
+    rx = 0
+    for s, w in zip(stages, raw_w, strict=True):
+        bars.append(
+            {
+                "x": rx,
+                "y": y,
+                "w": w,
+                "h": BAR_HEIGHT,
+                "tool_class": s.get("tool_class", s.get("dominant_class", "explore")),
+            }
+        )
+        rx += w + gap_px
+    return bars

{hyperweave-0.2.6 → hyperweave-0.2.8}/src/hyperweave/config/settings.py

@@ -37,7 +37,11 @@ class HyperWeaveSettings(BaseSettings):
     data_cache_ttl: int = Field(default=300, description="Data-bound artifact max-age (5 min)")
 
     # -- Connectors --
-    github_tokens: list[str] = Field(default_factory=list, description="GitHub API tokens for rotation")
+    # NOTE: GitHub token rotation lives in ``connectors.base._get_github_token``,
+    # which reads ``HW_GITHUB_TOKENS`` as a plain comma-separated string directly
+    # from ``os.environ``. Do NOT add a ``github_tokens`` Pydantic field here —
+    # Pydantic Settings would auto-map the same env var and try to JSON-parse
+    # the CSV value, crashing app startup.
     connect_timeout: float = Field(default=10.0, description="HTTP connect timeout in seconds")
     total_timeout: float = Field(default=15.0, description="HTTP total timeout in seconds")
 

{hyperweave-0.2.6 → hyperweave-0.2.8}/src/hyperweave/connectors/base.py

@@ -216,3 +216,66 @@ async def fetch_text(
         merged.update(headers)
     response = await fetch(url, provider=provider, headers=merged)
     return response.text
+
+
+# GraphQL POST
+
+_GITHUB_GRAPHQL_URL: str = "https://api.github.com/graphql"
+
+
+async def fetch_graphql(
+    query: str,
+    variables: dict[str, Any] | None = None,
+    *,
+    provider: str = "github",
+    url: str = _GITHUB_GRAPHQL_URL,
+) -> dict[str, Any]:
+    """POST a GraphQL query and return the parsed JSON response.
+
+    Mirrors :func:`fetch_json`'s contract (SSRF validation, per-provider
+    circuit breaker, timeouts, GitHub Bearer-token injection) but speaks
+    POST with a JSON body. The single GraphQL endpoint for GitHub is
+    baked into the default URL so callers don't have to remember it.
+
+    GraphQL always returns HTTP 200 with a ``data`` field and an optional
+    ``errors`` list — HTTP-level failures trip the breaker, but query-level
+    errors (invalid field, missing perms) come through as response body
+    and are the caller's responsibility to inspect.
+    """
+    validate_url(url)
+
+    breaker = get_breaker(provider)
+    if not breaker.allow_request():
+        raise CircuitOpenError(
+            f"Circuit breaker open for provider {provider!r}. Retry after {breaker.recovery_timeout}s."
+        )
+
+    merged_headers: dict[str, str] = {
+        "User-Agent": f"HyperWeave/{__version__} (https://hyperweave.app)",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if provider == "github":
+        token = _get_github_token()
+        if token:
+            merged_headers["Authorization"] = f"Bearer {token}"
+
+    timeout = httpx.Timeout(
+        connect=CONNECT_TIMEOUT,
+        read=TOTAL_TIMEOUT,
+        write=TOTAL_TIMEOUT,
+        pool=TOTAL_TIMEOUT,
+    )
+
+    body: dict[str, Any] = {"query": query, "variables": variables or {}}
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.post(url, headers=merged_headers, json=body)
+            response.raise_for_status()
+            breaker.record_success()
+            data: dict[str, Any] = response.json()
+            return data
+    except (httpx.HTTPStatusError, httpx.RequestError) as exc:
+        breaker.record_failure()
+        raise ConnectorError(f"GraphQL fetch failed for {provider!r}: {exc}") from exc