shellbrain 0.1.12__tar.gz → 0.1.14__tar.gz

{shellbrain-0.1.12 → shellbrain-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.12
+Version: 0.1.14
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -96,6 +96,19 @@ Fish PATH setup is written to `~/.config/fish/conf.d/shellbrain.fish`.
 
 ---
 
+## DB-backed tests
+
+**Live memories and DB-backed tests now use different Postgres hosts.**
+
+- managed local Shellbrain keeps durable memories on the machine-owned managed instance
+- DB-backed tests and scratch validation should use the dedicated repo-owned test host from `docker-compose.test.yml`
+- `scripts/run_tests` provisions a disposable test database on that dedicated host by default
+- `scripts/storage_status` shows the live managed target, the dedicated test host, and any legacy local test host that is still hanging around
+
+If you are running managed local Shellbrain, do not leave a stale `SHELLBRAIN_DB_DSN` export in your shell profile that points at the old local compose database. The machine config wins anyway, and the stale env var just makes the storage layout harder to reason about.
+
+---
+
 ## Docs
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started

{shellbrain-0.1.12 → shellbrain-0.1.14}/README.md

@@ -82,6 +82,19 @@ Fish PATH setup is written to `~/.config/fish/conf.d/shellbrain.fish`.
 
 ---
 
+## DB-backed tests
+
+**Live memories and DB-backed tests now use different Postgres hosts.**
+
+- managed local Shellbrain keeps durable memories on the machine-owned managed instance
+- DB-backed tests and scratch validation should use the dedicated repo-owned test host from `docker-compose.test.yml`
+- `scripts/run_tests` provisions a disposable test database on that dedicated host by default
+- `scripts/storage_status` shows the live managed target, the dedicated test host, and any legacy local test host that is still hanging around
+
+If you are running managed local Shellbrain, do not leave a stale `SHELLBRAIN_DB_DSN` export in your shell profile that points at the old local compose database. The machine config wins anyway, and the stale env var just makes the storage layout harder to reason about.
+
+---
+
 ## Docs
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/core/interfaces/repos.py

@@ -85,6 +85,14 @@ class IEpisodesRepo(ABC):
     def create_episode(self, episode: Episode) -> None:
         """This method persists an episode row."""
 
+    @abstractmethod
+    def acquire_thread_sync_guard(self, *, repo_id: str, thread_id: str) -> None:
+        """This method serializes sync writes for one repo/thread pair."""
+
+    @abstractmethod
+    def get_or_create_episode_for_thread(self, episode: Episode) -> Episode:
+        """This method returns the canonical episode row for one thread, creating it when missing."""
+
     @abstractmethod
     def get_episode_by_thread(
         self,
@@ -106,6 +114,10 @@ class IEpisodesRepo(ABC):
     def append_event(self, event: EpisodeEvent) -> None:
         """This method appends an event into an episode stream."""
 
+    @abstractmethod
+    def append_event_if_new(self, event: EpisodeEvent) -> bool:
+        """This method appends an event only when its host_event_key is not already present."""
+
     @abstractmethod
     def close_episode(self, *, episode_id: str, ended_at: datetime) -> None:
         """This method marks an active episode closed."""

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/core/policies/_shared/executor.py

@@ -52,7 +52,7 @@ def apply_side_effects(
         if effect_type == "memory_evidence.attach":
             refs = params["refs"]
             assert isinstance(refs, list)
-            for ref in refs:
+            for ref in sorted(str(ref) for ref in refs):
                 evidence = uow.evidence.upsert_ref(repo_id=str(params["repo_id"]), ref=str(ref))
                 uow.evidence.link_memory_evidence(memory_id=str(params["memory_id"]), evidence_id=evidence.id)
             continue
@@ -124,7 +124,7 @@ def apply_side_effects(
             )
             evidence_refs = params.get("evidence_refs", [])
             assert isinstance(evidence_refs, list)
-            for ref in evidence_refs:
+            for ref in sorted(str(ref) for ref in evidence_refs):
                 evidence = uow.evidence.upsert_ref(repo_id=str(params["repo_id"]), ref=str(ref))
                 uow.evidence.link_association_edge_evidence(edge_id=edge.id, evidence_id=evidence.id)
             continue

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/core/use_cases/sync_episode.py

@@ -25,12 +25,11 @@ def sync_episode(
     """Import one already-normalized host transcript into episodes and episode events."""
 
     counts = _count_normalized_events(normalized_events)
-    episode = uow.episodes.get_episode_by_thread(repo_id=repo_id, thread_id=thread_id)
+    uow.episodes.acquire_thread_sync_guard(repo_id=repo_id, thread_id=thread_id)
     imported_count = 0
-
-    if episode is None:
-        started_at = _earliest_event_timestamp(normalized_events) or datetime.now(timezone.utc)
-        episode = Episode(
+    started_at = _earliest_event_timestamp(normalized_events) or datetime.now(timezone.utc)
+    episode = uow.episodes.get_or_create_episode_for_thread(
+        Episode(
             id=str(uuid4()),
             repo_id=repo_id,
             host_app=host_app,
@@ -39,17 +38,13 @@ def sync_episode(
             started_at=started_at,
             created_at=datetime.now(timezone.utc),
         )
-        uow.episodes.create_episode(episode)
-
-    existing_keys = set(uow.episodes.list_event_keys(episode_id=episode.id))
+    )
     next_seq = uow.episodes.next_event_seq(episode_id=episode.id)
     for normalized_event in normalized_events:
         host_event_key = str(normalized_event["host_event_key"])
-        if host_event_key in existing_keys:
-            continue
         created_at = _parse_timestamp(str(normalized_event["occurred_at"]))
         source = EpisodeEventSource(str(normalized_event["source"]))
-        uow.episodes.append_event(
+        inserted = uow.episodes.append_event_if_new(
             EpisodeEvent(
                 id=str(uuid4()),
                 episode_id=episode.id,
@@ -60,7 +55,8 @@ def sync_episode(
                 created_at=created_at,
             )
         )
-        existing_keys.add(host_event_key)
+        if not inserted:
+            continue
         next_seq += 1
         imported_count += 1
 

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/periphery/admin/analytics_diagnostics.py

@@ -13,7 +13,7 @@ def classify_operation_failure(
     """Return one stable diagnosis payload for an operation failure."""
 
     message = (error_message or "").lower()
-    if "uq_evidence_repo_ref" in message:
+    if "uq_evidence_repo_ref" in message or "uq_evidence_repo_episode_event" in message:
         return _diagnosis(
             category="duplicate_evidence_ref",
             summary="Evidence refs are being inserted twice for the same repo/event pair.",

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/periphery/admin/instance_guard.py

@@ -45,17 +45,36 @@ def dsn_fingerprint(dsn: str) -> str:
     return hashlib.sha256(normalize_dsn(dsn).encode("utf-8")).hexdigest()
 
 
+def host_port_from_dsn(dsn: str) -> tuple[str, int]:
+    """Extract the normalized host/port pair from one DSN."""
+
+    parsed = urlparse(dsn.replace("+psycopg", ""))
+    return ((parsed.hostname or "").lower(), parsed.port or 5432)
+
+
 def database_name_from_dsn(dsn: str) -> str:
     """Extract the target database name from one DSN."""
 
     return urlparse(dsn.replace("+psycopg", "")).path.lstrip("/")
 
 
-def assert_disposable_test_dsn(*, test_dsn: str, protected_dsn: str | None = None) -> None:
+def assert_disposable_test_dsn(
+    *,
+    test_dsn: str,
+    protected_dsn: str | None = None,
+    protected_host_ports: set[tuple[str, int]] | None = None,
+) -> None:
     """Refuse to treat a protected or production-shaped database as disposable."""
 
     if protected_dsn and dsn_fingerprint(test_dsn) == dsn_fingerprint(protected_dsn):
         raise RuntimeError("Refusing destructive test setup against the protected live database DSN.")
+    protected_pairs = set(protected_host_ports or set())
+    if protected_dsn:
+        protected_pairs.add(host_port_from_dsn(protected_dsn))
+    if host_port_from_dsn(test_dsn) in protected_pairs:
+        raise RuntimeError(
+            "Refusing destructive test setup against the protected live database host/port."
+        )
     db_name = database_name_from_dsn(test_dsn).lower()
     if db_name in PROTECTED_DB_NAMES:
         raise RuntimeError(

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/periphery/cli/main.py

@@ -60,6 +60,7 @@ _TOP_LEVEL_HELP = dedent(
     Examples:
       shellbrain init
       shellbrain upgrade
+      shellbrain metrics --days 30
       shellbrain read --json '{"query":"Have we seen this migration lock timeout before?","kinds":["problem","solution","failed_tactic"]}'
       shellbrain read --json '{"query":"What repo constraints or user preferences matter for this auth refactor?","kinds":["fact","preference","change"]}'
       shellbrain events --json '{"limit":10}'
@@ -229,6 +230,17 @@ _ANALYTICS_HELP = dedent(
     """
 )
 
+_METRICS_HELP = dedent(
+    """\
+    Generate one lightweight repo-scoped metrics snapshot, write local artifacts, and open a static dashboard.
+
+    Examples:
+      shellbrain metrics
+      shellbrain metrics --days 30
+      shellbrain metrics --days 14 --no-open
+    """
+)
+
 _INSTALL_CLAUDE_HOOK_HELP = dedent(
     """\
     Install or update the repo-local Claude Code SessionStart hook used as an explicit repo-local override.
@@ -344,6 +356,26 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=_HelpFormatter,
     )
 
+    metrics_parser = subparsers.add_parser(
+        "metrics",
+        help="Open a lightweight repo-scoped metrics dashboard.",
+        description="Generate one local metrics snapshot and open a static Shellbrain dashboard.",
+        epilog=_METRICS_HELP,
+        formatter_class=_HelpFormatter,
+    )
+    _add_repo_context_arguments(metrics_parser, suppress_default=True)
+    metrics_parser.add_argument(
+        "--days",
+        type=int,
+        default=30,
+        help="Number of trailing days to include in the snapshot. Defaults to 30.",
+    )
+    metrics_parser.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Generate artifacts without opening the dashboard in the browser.",
+    )
+
     create_parser = subparsers.add_parser(
         "create",
         help="Create one Shellbrain entry from explicit evidence.",
@@ -523,6 +555,9 @@ def main(argv: Sequence[str] | None = None) -> int:
 
         return run_upgrade()
 
+    if args.command == "metrics":
+        return _run_metrics_command(args)
+
     if args.command == "admin":
         return _run_admin_command(args)
 
@@ -776,6 +811,58 @@ def _run_admin_command(args: argparse.Namespace) -> int:
     raise ValueError(f"Unsupported admin command: {args.admin_command}")
 
 
+def _run_metrics_command(args: argparse.Namespace) -> int:
+    """Generate one repo-scoped metrics snapshot and local dashboard artifacts."""
+
+    try:
+        from app.boot.admin_db import get_optional_admin_db_dsn
+        from app.boot.db import get_optional_db_dsn
+        from app.periphery.db.engine import get_engine
+        from app.periphery.metrics.artifacts import write_metrics_artifacts
+        from app.periphery.metrics.browser import open_metrics_dashboard
+        from app.periphery.metrics.render_html import render_metrics_dashboard
+        from app.periphery.metrics.service import build_metrics_snapshot
+
+        repo_context = resolve_repo_context(
+            repo_root_arg=getattr(args, "repo_root", None),
+            repo_id_arg=getattr(args, "repo_id", None),
+        )
+        _warn_or_fail_on_unsafe_app_role()
+        _ensure_repo_registration_for_operation(
+            repo_context=repo_context,
+            repo_id_override=getattr(args, "repo_id", None),
+        )
+        dsn = get_optional_db_dsn() or get_optional_admin_db_dsn()
+        if not dsn:
+            raise RuntimeError("Shellbrain database is not configured. Run `shellbrain init` first.")
+        snapshot = build_metrics_snapshot(
+            engine=get_engine(dsn),
+            repo_id=repo_context.repo_id,
+            days=int(args.days),
+        )
+        html = render_metrics_dashboard(snapshot)
+        paths = write_metrics_artifacts(repo_id=repo_context.repo_id, snapshot=snapshot, html=html)
+        opened_dashboard = False
+        if not bool(getattr(args, "no_open", False)):
+            opened_dashboard = bool(open_metrics_dashboard(paths["html_path"]))
+        print(f"Generated Shellbrain metrics for {repo_context.repo_id}")
+        print(f"Status: {snapshot['status']} ({snapshot['confidence']} confidence)")
+        print(f"JSON: {paths['json_path']}")
+        print(f"Markdown: {paths['md_path']}")
+        print(f"Dashboard: {paths['html_path']}")
+        print("Artifacts: updated in place")
+        if bool(getattr(args, "no_open", False)):
+            print("Browser: skipped")
+        elif opened_dashboard:
+            print("Browser: opened dashboard")
+        else:
+            print("Browser: could not open automatically")
+        return 0
+    except (RuntimeError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
 def _print_operation_result(result: dict[str, Any]) -> None:
     """Render one operation result as JSON for agent consumption."""
 

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/periphery/db/repos/relational/episodes_repo.py

@@ -3,7 +3,8 @@
 from datetime import datetime, timezone
 from typing import Sequence
 
-from sqlalchemy import func, select, update
+from sqlalchemy import func, select, text, update
+from sqlalchemy.dialects.postgresql import insert
 
 from app.core.entities.episodes import Episode, EpisodeEvent, EpisodeEventSource, EpisodeStatus, SessionTransfer
 from app.core.interfaces.repos import IEpisodesRepo
@@ -36,6 +37,40 @@ class EpisodesRepo(IEpisodesRepo):
             )
         )
 
+    def acquire_thread_sync_guard(self, *, repo_id: str, thread_id: str) -> None:
+        """This method serializes sync writes for one repo/thread pair."""
+
+        self._session.execute(
+            text("SELECT pg_advisory_xact_lock(hashtext(:repo_id), hashtext(:thread_id))"),
+            {"repo_id": repo_id, "thread_id": thread_id},
+        )
+
+    def get_or_create_episode_for_thread(self, episode: Episode) -> Episode:
+        """This method returns the canonical episode row for one thread, creating it when missing."""
+
+        if episode.thread_id is None:
+            raise ValueError("thread_id is required when ensuring an episode for sync")
+        self._session.execute(
+            insert(episodes)
+            .values(
+                id=episode.id,
+                repo_id=episode.repo_id,
+                host_app=episode.host_app,
+                thread_id=episode.thread_id,
+                title=episode.title,
+                objective=episode.objective,
+                status=episode.status.value,
+                started_at=episode.started_at or datetime.now(timezone.utc),
+                ended_at=episode.ended_at,
+                created_at=episode.created_at or datetime.now(timezone.utc),
+            )
+            .on_conflict_do_nothing(index_elements=["repo_id", "thread_id"])
+        )
+        stored = self.get_episode_by_thread(repo_id=episode.repo_id, thread_id=episode.thread_id)
+        if stored is None:
+            raise RuntimeError("episode ensure failed to return a canonical thread row")
+        return stored
+
     def get_episode_by_thread(
         self,
         *,
@@ -100,6 +135,25 @@ class EpisodesRepo(IEpisodesRepo):
             )
         )
 
+    def append_event_if_new(self, event: EpisodeEvent) -> bool:
+        """This method appends an episode event only when its host_event_key is new."""
+
+        inserted_id = self._session.execute(
+            insert(episode_events)
+            .values(
+                id=event.id,
+                episode_id=event.episode_id,
+                seq=event.seq,
+                host_event_key=event.host_event_key,
+                source=event.source.value,
+                content=event.content,
+                created_at=event.created_at or datetime.now(timezone.utc),
+            )
+            .on_conflict_do_nothing(index_elements=["episode_id", "host_event_key"])
+            .returning(episode_events.c.id)
+        ).scalar_one_or_none()
+        return inserted_id is not None
+
     def close_episode(self, *, episode_id: str, ended_at: datetime) -> None:
         """This method marks an active episode closed."""
 

{shellbrain-0.1.12 → shellbrain-0.1.14}/app/periphery/db/repos/relational/evidence_repo.py

@@ -3,7 +3,7 @@
 from datetime import datetime, timezone
 from uuid import uuid4
 
-from sqlalchemy import select, update
+from sqlalchemy import select, text, update
 from sqlalchemy.dialects.postgresql import insert
 
 from app.core.entities.evidence import EvidenceRef
@@ -24,6 +24,7 @@ class EvidenceRepo(IEvidenceRepo):
     def upsert_ref(self, repo_id: str, ref: str) -> EvidenceRef:
         """This method inserts or returns a canonical evidence reference row."""
 
+        self._acquire_ref_guard(repo_id=repo_id, ref=ref)
         existing = (
             self._session.execute(
                 select(evidence_refs).where(
@@ -63,6 +64,14 @@ class EvidenceRepo(IEvidenceRepo):
         )
         return EvidenceRef(id=evidence_id, repo_id=repo_id, ref=ref, episode_event_id=ref)
 
+    def _acquire_ref_guard(self, *, repo_id: str, ref: str) -> None:
+        """Serialize concurrent writes for one repo/ref pair within the active transaction."""
+
+        self._session.execute(
+            text("SELECT pg_advisory_xact_lock(hashtext(:repo_id), hashtext(:ref))"),
+            {"repo_id": repo_id, "ref": ref},
+        )
+
     def link_memory_evidence(self, memory_id: str, evidence_id: str) -> None:
         """This method creates shellbrain-to-evidence link rows."""
 

shellbrain-0.1.14/app/periphery/metrics/__init__.py

@@ -0,0 +1 @@
+"""Periphery-only helpers for the Shellbrain metrics dashboard."""

shellbrain-0.1.14/app/periphery/metrics/artifacts.py

@@ -0,0 +1,44 @@
+"""Artifact helpers for generated metrics snapshots and dashboards."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+from app.boot.home import get_shellbrain_home
+
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def get_metrics_artifact_dir(*, repo_id: str) -> Path:
+    """Return the machine-owned artifact directory for one repo's metrics outputs."""
+
+    normalized = _NON_ALNUM.sub("-", repo_id.lower()).strip("-") or "repo"
+    digest = hashlib.sha1(repo_id.encode("utf-8")).hexdigest()[:8]
+    return get_shellbrain_home() / "reports" / "metrics" / f"{normalized}-{digest}"
+
+
+def write_metrics_artifacts(*, repo_id: str, snapshot: dict[str, Any], html: str) -> dict[str, Path]:
+    """Write the latest metrics snapshot, markdown summary, and dashboard HTML."""
+
+    artifact_dir = get_metrics_artifact_dir(repo_id=repo_id)
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+
+    json_path = artifact_dir / "latest.json"
+    md_path = artifact_dir / "latest.md"
+    html_path = artifact_dir / "dashboard.html"
+
+    json_path.write_text(json.dumps(snapshot, indent=2, sort_keys=True), encoding="utf-8")
+    md_path.write_text(str(snapshot["summary_md"]).strip() + "\n", encoding="utf-8")
+    html_path.write_text(html, encoding="utf-8")
+
+    return {
+        "artifact_dir": artifact_dir,
+        "json_path": json_path,
+        "md_path": md_path,
+        "html_path": html_path,
+    }

shellbrain-0.1.14/app/periphery/metrics/browser.py

@@ -0,0 +1,12 @@
+"""Browser helpers for opening generated metrics dashboards."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import webbrowser
+
+
+def open_metrics_dashboard(path: Path) -> bool:
+    """Open one generated dashboard in the default browser."""
+
+    return bool(webbrowser.open(path.resolve().as_uri()))

shellbrain-0.1.14/app/periphery/metrics/queries.py

@@ -0,0 +1,192 @@
+"""SQL query helpers for repo-scoped Shellbrain metrics snapshots."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection
+
+
+def fetch_daily_utility_rows(
+    *,
+    conn: Connection,
+    repo_id: str,
+    start_at: datetime,
+    end_at: datetime,
+) -> list[dict[str, object]]:
+    """Return daily utility vote aggregates for one repo and time range."""
+
+    rows = conn.execute(
+        text(
+            """
+            SELECT
+              date_trunc('day', u.created_at AT TIME ZONE 'UTC') AS day_utc,
+              COUNT(*)::INTEGER AS vote_count,
+              COALESCE(SUM(u.vote), 0)::DOUBLE PRECISION AS vote_sum
+            FROM utility_observations u
+            JOIN memories problem_mem ON problem_mem.id = u.problem_id
+            WHERE problem_mem.repo_id = :repo_id
+              AND u.created_at >= :start_at
+              AND u.created_at < :end_at
+            GROUP BY date_trunc('day', u.created_at AT TIME ZONE 'UTC')
+            ORDER BY day_utc ASC;
+            """
+        ),
+        {"repo_id": repo_id, "start_at": start_at, "end_at": end_at},
+    ).mappings()
+    return [dict(row) for row in rows]
+
+
+def fetch_daily_followthrough_rows(
+    *,
+    conn: Connection,
+    repo_id: str,
+    start_at: datetime,
+    end_at: datetime,
+) -> list[dict[str, object]]:
+    """Return daily utility-guidance follow-through counts for one repo and time range."""
+
+    rows = conn.execute(
+        text(
+            """
+            WITH pending_threads AS (
+              SELECT
+                oi.repo_id,
+                oi.selected_thread_id,
+                MIN(oi.created_at) AS first_guidance_at
+              FROM operation_invocations oi
+              WHERE oi.repo_id = :repo_id
+                AND oi.created_at >= :start_at
+                AND oi.created_at < :end_at
+                AND oi.selected_thread_id IS NOT NULL
+                AND oi.guidance_codes @> '["pending_utility_votes"]'::jsonb
+              GROUP BY oi.repo_id, oi.selected_thread_id
+            ),
+            vote_threads AS (
+              SELECT
+                oi.repo_id,
+                oi.selected_thread_id,
+                MIN(oi.created_at) AS first_vote_at
+              FROM write_invocation_summaries wis
+              JOIN operation_invocations oi ON oi.id = wis.invocation_id
+              WHERE oi.repo_id = :repo_id
+                AND oi.created_at >= :start_at
+                AND oi.created_at < :end_at
+                AND oi.selected_thread_id IS NOT NULL
+                AND wis.update_type IN ('utility_vote', 'utility_vote_batch')
+              GROUP BY oi.repo_id, oi.selected_thread_id
+            )
+            SELECT
+              date_trunc('day', pending.first_guidance_at AT TIME ZONE 'UTC') AS day_utc,
+              COUNT(*)::INTEGER AS opportunity_count,
+              COUNT(*) FILTER (
+                WHERE votes.first_vote_at IS NOT NULL
+                  AND votes.first_vote_at > pending.first_guidance_at
+              )::INTEGER AS followthrough_count
+            FROM pending_threads pending
+            LEFT JOIN vote_threads votes
+              ON votes.repo_id = pending.repo_id
+             AND votes.selected_thread_id = pending.selected_thread_id
+            GROUP BY date_trunc('day', pending.first_guidance_at AT TIME ZONE 'UTC')
+            ORDER BY day_utc ASC;
+            """
+        ),
+        {"repo_id": repo_id, "start_at": start_at, "end_at": end_at},
+    ).mappings()
+    return [dict(row) for row in rows]
+
+
+def fetch_daily_zero_result_rows(
+    *,
+    conn: Connection,
+    repo_id: str,
+    start_at: datetime,
+    end_at: datetime,
+) -> list[dict[str, object]]:
+    """Return daily read and zero-result counts for one repo and time range."""
+
+    rows = conn.execute(
+        text(
+            """
+            SELECT
+              date_trunc('day', oi.created_at AT TIME ZONE 'UTC') AS day_utc,
+              COUNT(*)::INTEGER AS read_count,
+              COUNT(*) FILTER (WHERE ris.zero_results)::INTEGER AS zero_result_count
+            FROM read_invocation_summaries ris
+            JOIN operation_invocations oi ON oi.id = ris.invocation_id
+            WHERE oi.repo_id = :repo_id
+              AND oi.created_at >= :start_at
+              AND oi.created_at < :end_at
+            GROUP BY date_trunc('day', oi.created_at AT TIME ZONE 'UTC')
+            ORDER BY day_utc ASC;
+            """
+        ),
+        {"repo_id": repo_id, "start_at": start_at, "end_at": end_at},
+    ).mappings()
+    return [dict(row) for row in rows]
+
+
+def fetch_daily_events_before_write_rows(
+    *,
+    conn: Connection,
+    repo_id: str,
+    start_at: datetime,
+    end_at: datetime,
+) -> list[dict[str, object]]:
+    """Return daily write counts and events-before-write compliance for one repo."""
+
+    rows = conn.execute(
+        text(
+            """
+            SELECT
+              date_trunc('day', oi.created_at AT TIME ZONE 'UTC') AS day_utc,
+              COUNT(*)::INTEGER AS write_count,
+              COUNT(*) FILTER (
+                WHERE EXISTS (
+                  SELECT 1
+                  FROM operation_invocations prior_events
+                  WHERE prior_events.repo_id = oi.repo_id
+                    AND prior_events.selected_thread_id = oi.selected_thread_id
+                    AND prior_events.command = 'events'
+                    AND prior_events.created_at < oi.created_at
+                )
+              )::INTEGER AS compliant_count
+            FROM write_invocation_summaries wis
+            JOIN operation_invocations oi ON oi.id = wis.invocation_id
+            WHERE oi.repo_id = :repo_id
+              AND oi.created_at >= :start_at
+              AND oi.created_at < :end_at
+            GROUP BY date_trunc('day', oi.created_at AT TIME ZONE 'UTC')
+            ORDER BY day_utc ASC;
+            """
+        ),
+        {"repo_id": repo_id, "start_at": start_at, "end_at": end_at},
+    ).mappings()
+    return [dict(row) for row in rows]
+
+
+def fetch_sync_health_summary(
+    *,
+    conn: Connection,
+    repo_id: str,
+    start_at: datetime,
+    end_at: datetime,
+) -> dict[str, object]:
+    """Return current-window sync health counts for one repo."""
+
+    row = conn.execute(
+        text(
+            """
+            SELECT
+              COUNT(*)::INTEGER AS sync_run_count,
+              COUNT(*) FILTER (WHERE outcome = 'error')::INTEGER AS failed_sync_count
+            FROM episode_sync_runs
+            WHERE repo_id = :repo_id
+              AND created_at >= :start_at
+              AND created_at < :end_at;
+            """
+        ),
+        {"repo_id": repo_id, "start_at": start_at, "end_at": end_at},
+    ).mappings().one()
+    return dict(row)