claude-sql 0.5.0__tar.gz → 0.6.0__tar.gz

{claude_sql-0.5.0 → claude_sql-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: claude-sql
-Version: 0.5.0
+Version: 0.6.0
 Summary: Zero-copy SQL + semantic search + LLM analytics over ~/.claude/ transcripts.
 Keywords: claude,claude-code,anthropic,duckdb,sql,semantic-search,embeddings,bedrock,transcripts,analytics,observability
 Author: Laith Al-Saadoon
@@ -336,6 +336,7 @@ Commands that spend real Bedrock money default to `--dry-run`.
 
 | Macro | Signature | What it does |
 |---|---|---|
+| `ago(interval_text)` | scalar → `TIMESTAMP` | `current_timestamp - INTERVAL <text>` -- e.g. `WHERE ts >= ago('30 days')` |
 | `model_used(sid)` | scalar → `VARCHAR` | Latest `model` observed in the session |
 | `cost_estimate(sid)` | scalar → `DOUBLE` | USD spend (dated model IDs prefix-matched) |
 | `tool_rank(last_n_days)` | table | Tool-use leaderboard over a window |

{claude_sql-0.5.0 → claude_sql-0.6.0}/README.md

@@ -290,6 +290,7 @@ Commands that spend real Bedrock money default to `--dry-run`.
 
 | Macro | Signature | What it does |
 |---|---|---|
+| `ago(interval_text)` | scalar → `TIMESTAMP` | `current_timestamp - INTERVAL <text>` -- e.g. `WHERE ts >= ago('30 days')` |
 | `model_used(sid)` | scalar → `VARCHAR` | Latest `model` observed in the session |
 | `cost_estimate(sid)` | scalar → `DOUBLE` | USD spend (dated model IDs prefix-matched) |
 | `tool_rank(last_n_days)` | table | Tool-use leaderboard over a window |

{claude_sql-0.5.0 → claude_sql-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "claude-sql"
-version = "0.5.0"
+version = "0.6.0"
 description = "Zero-copy SQL + semantic search + LLM analytics over ~/.claude/ transcripts."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{claude_sql-0.5.0 → claude_sql-0.6.0}/src/claude_sql/cli.py

@@ -30,6 +30,7 @@ import tempfile
 import time
 from dataclasses import dataclass
 from datetime import UTC, datetime
+from enum import StrEnum
 from pathlib import Path
 from typing import Annotated
 
@@ -81,8 +82,11 @@ from claude_sql.parquet_shards import (
 from claude_sql.review_sheet_render import render_markdown, render_refusal_markdown
 from claude_sql.review_sheet_worker import generate_review_sheet
 from claude_sql.sql_views import (
-    describe_all,
-    list_macros,
+    MACRO_NAMES,
+    MACRO_SIGNATURES,
+    VIEW_NAMES,
+    VIEW_SCHEMA,
+    _parquet_is_populated,
     register_all,
     register_raw,
     register_views,
@@ -103,12 +107,19 @@ Surfaces at a glance
   cluster / terms / community     UMAP+HDBSCAN, c-TF-IDF, Leiden+CPM
   analyze                         composite pipeline over every stage above
 
-Flag placement (important for agents)
--------------------------------------
-All flags attach to a SUBCOMMAND, not the top-level binary. Correct:
+!! FLAG PLACEMENT — flags attach to a SUBCOMMAND, not the binary !!
+-------------------------------------------------------------------
+Every flag (--format, --quiet, --verbose, --glob, --subagent-glob, and
+every per-command flag) goes AFTER the subcommand name. This applies
+to global-feeling flags too: `--quiet` must come after the subcommand.
+
+OK:
     claude-sql query --format json "SELECT 1"
+    claude-sql schema --quiet --format json
     claude-sql classify --no-dry-run --limit 5
-Incorrect (flag gets swallowed as the subcommand argument):
+FAIL (cyclopts: "Unused Tokens: ['schema']"):
+    claude-sql --quiet schema --format json
+FAIL (flag swallowed as subcommand arg):
     claude-sql --format json query "SELECT 1"
 
 Output & exit codes
@@ -244,15 +255,15 @@ def _resolve_memory_limit(limit: str) -> str:
     return f"{target_mib}MiB"
 
 
-def _open_connection(settings: Settings) -> duckdb.DuckDBPyConnection:
-    """Open an in-memory DuckDB connection with every claude-sql object wired.
+def _apply_duckdb_pragmas(con: duckdb.DuckDBPyConnection, settings: Settings) -> None:
+    """Set the tuning PRAGMAs both connection helpers share.
 
-    Tuning PRAGMAs are set before view registration so the registration
-    queries themselves benefit from the higher thread count and the spill
-    directory pointed at real disk (Amazon devboxes ship ``/tmp`` as a
-    4 GB tmpfs that thrashes once a clustering run starts spilling).
+    Centralized so :func:`_open_connection_full` and
+    :func:`_open_connection_introspect` stay in sync. Threads, memory_limit,
+    and temp_directory all come from ``settings``; the spill directory is
+    materialized on disk before DuckDB sees the path because DuckDB will
+    happily fail later when it tries to write a spill file.
     """
-    con = duckdb.connect(":memory:")
     settings.duckdb_temp_dir.mkdir(parents=True, exist_ok=True)
     memory_limit = _resolve_memory_limit(settings.duckdb_memory_limit)
     con.execute(f"SET threads = {int(settings.duckdb_threads)}")
@@ -260,10 +271,48 @@ def _open_connection(settings: Settings) -> duckdb.DuckDBPyConnection:
     con.execute(f"SET temp_directory = '{settings.duckdb_temp_dir}'")
     con.execute("SET enable_object_cache = true")
     con.execute("SET preserve_insertion_order = false")
+
+
+def _open_connection_full(settings: Settings) -> duckdb.DuckDBPyConnection:
+    """Open an in-memory DuckDB connection with every claude-sql object wired.
+
+    Tuning PRAGMAs are set before view registration so the registration
+    queries themselves benefit from the higher thread count and the spill
+    directory pointed at real disk (Amazon devboxes ship ``/tmp`` as a
+    4 GB tmpfs that thrashes once a clustering run starts spilling).
+    """
+    con = duckdb.connect(":memory:")
+    _apply_duckdb_pragmas(con, settings)
     register_all(con, settings=settings)
     return con
 
 
+def _open_connection_introspect(settings: Settings) -> duckdb.DuckDBPyConnection:
+    """Bare DuckDB connection — PRAGMAs only, no view/macro registration.
+
+    For commands that don't need the catalog (``schema`` reads the static
+    :data:`VIEW_SCHEMA` dict; trivial scalar queries like ``SELECT 1`` or
+    ``SELECT current_timestamp`` don't reference any view). Returning a
+    bare connection avoids the ~25 s :func:`register_all` chain entirely.
+    """
+    con = duckdb.connect(":memory:")
+    _apply_duckdb_pragmas(con, settings)
+    return con
+
+
+def _sql_uses_catalog(sql: str) -> bool:
+    """Cheap pre-flight: does ``sql`` reference any registered view/macro?
+
+    Substring-matches against ``VIEW_NAMES + MACRO_NAMES`` (case-insensitive).
+    False positives (a string literal containing ``'sessions'``) just trigger
+    the slow path — no correctness regression. False negatives can't happen
+    if the user genuinely references a view: the name has to appear in the
+    SQL text.
+    """
+    lowered = sql.lower()
+    return any(name.lower() in lowered for name in (*VIEW_NAMES, *MACRO_NAMES))
+
+
 def _emit_worker_result(result: int | dict, common: Common | None, pipeline: str) -> None:
     """Normalize worker results for stdout.
 
@@ -515,7 +564,11 @@ def query(
     _configure(common)
     settings = _resolve_settings(common)
     fmt = _fmt(common)
-    con = _open_connection(settings)
+    con = (
+        _open_connection_full(settings)
+        if _sql_uses_catalog(sql)
+        else _open_connection_introspect(settings)
+    )
     try:
         profile_path: Path | None = None
         if profile_json:
@@ -561,7 +614,11 @@ def explain(
     _configure(common)
     settings = _resolve_settings(common)
     fmt = resolve_format(_fmt(common))
-    con = _open_connection(settings)
+    con = (
+        _open_connection_full(settings)
+        if _sql_uses_catalog(sql)
+        else _open_connection_introspect(settings)
+    )
     try:
         profile_path: Path | None = None
         if profile_json:
@@ -585,9 +642,58 @@ def explain(
         con.close()
 
 
+def _compute_cached_map(settings: Settings) -> dict[str, bool]:
+    """Map analytics view + analytics macro names to parquet-existence.
+
+    A name appears in this map when its data lives in a parquet that may
+    or may not exist on disk (the v2 analytics surface). v1 views always
+    have data (the transcript globs are always present), so they don't
+    appear here. Use ``list-cache`` for byte counts / mtimes / row counts.
+    """
+    # Analytics view → backing parquet path on Settings.
+    view_paths: dict[str, Path] = {
+        "session_classifications": settings.classifications_parquet_path,
+        "session_goals": settings.classifications_parquet_path,
+        "message_trajectory": settings.trajectory_parquet_path,
+        "session_conflicts": settings.conflicts_parquet_path,
+        "message_clusters": settings.clusters_parquet_path,
+        "cluster_terms": settings.cluster_terms_parquet_path,
+        "session_communities": settings.communities_parquet_path,
+        "community_profile": settings.community_profile_parquet_path,
+        "user_friction": settings.user_friction_parquet_path,
+        "skills_catalog": settings.skills_catalog_parquet_path,
+        "skill_usage": settings.skills_catalog_parquet_path,
+    }
+    cached: dict[str, bool] = {
+        name: _parquet_is_populated(path) for name, path in view_paths.items()
+    }
+    # Analytics macros depend on the same parquets as their backing views;
+    # surface them too so an agent asking "is friction_rate ready?" gets a
+    # direct yes/no without re-deriving the dependency.
+    macro_paths: dict[str, tuple[Path, ...]] = {
+        "autonomy_trend": (settings.classifications_parquet_path,),
+        "work_mix": (settings.classifications_parquet_path,),
+        "success_rate_by_work": (settings.classifications_parquet_path,),
+        "cluster_top_terms": (settings.cluster_terms_parquet_path,),
+        "community_top_topics": (
+            settings.cluster_terms_parquet_path,
+            settings.communities_parquet_path,
+            settings.clusters_parquet_path,
+        ),
+        "sentiment_arc": (settings.trajectory_parquet_path,),
+        "friction_counts": (settings.user_friction_parquet_path,),
+        "friction_rate": (settings.user_friction_parquet_path,),
+        "friction_examples": (settings.user_friction_parquet_path,),
+        "unused_skills": (settings.skills_catalog_parquet_path,),
+    }
+    for macro_name, paths in macro_paths.items():
+        cached[macro_name] = all(_parquet_is_populated(p) for p in paths)
+    return cached
+
+
 @app.command
 def schema(*, common: Common | None = None) -> None:
-    """List every registered view (with columns) and every macro in one pass.
+    """List every registered view (with columns) and every macro signature.
 
     When to use
     -----------
@@ -596,6 +702,15 @@ def schema(*, common: Common | None = None) -> None:
     calls -- e.g., ``session_classifications`` uses both ``autonomy_tier``
     (canonical) and ``autonomy`` (alias), and the schema lists both.
 
+    Implementation
+    --------------
+    Reads the static :data:`VIEW_SCHEMA` and :data:`MACRO_SIGNATURES`
+    dicts -- no DuckDB connection, no JSON schema inference, no view
+    registration. Sub-50ms even on large corpora. The ``cached`` map is
+    keyed by analytics view + analytics macro names so an agent can tell
+    which parquet-backed entries are populated; use ``list-cache`` for
+    byte counts and mtimes.
+
     Output shape (non-TTY / JSON)
     -----------------------------
     ::
@@ -604,42 +719,39 @@ def schema(*, common: Common | None = None) -> None:
           "views": {
             "sessions": [{"column": "session_id", "type": "VARCHAR"}, ...],
             "messages": [...],
-            "session_classifications": [...],   // only if parquet exists
             ...
           },
-          "macros": ["autonomy_trend", "conflict_rate", ...]
+          "macros": [{"name": "ago", "params": ["interval_text"]}, ...],
+          "cached": {"user_friction": false, "friction_rate": false, ...}
         }
 
-    Missing analytics parquets are silently omitted (register_analytics
-    skips them). Use ``list-cache`` to see which generators still need to
-    run.
+    Only v1 (transcript-derived) views appear under ``views`` -- v2
+    analytics views are parquet-backed; their schema source-of-truth is
+    the parquet metadata. Use ``cached`` to see which v2 views can be
+    queried right now.
     """
     _configure(common)
     settings = _resolve_settings(common)
     fmt = resolve_format(_fmt(common))
-    con = _open_connection(settings)
-    try:
-        views = describe_all(con)
-        macros = list_macros(con)
-        if fmt is OutputFormat.TABLE:
-            for name, cols in views.items():
-                print(f"\n\033[1m{name}\033[0m ({len(cols)} cols)")
-                for col, col_type in cols:
-                    print(f"  {col:<28} {col_type}")
-            print(f"\n\033[1mMacros\033[0m ({len(macros)})")
-            for macro in macros:
-                print(f"  {macro}")
-        else:
-            payload = {
-                "views": {
-                    name: [{"column": c, "type": t} for c, t in cols]
-                    for name, cols in views.items()
-                },
-                "macros": list(macros),
-            }
-            emit_json(payload, fmt)
-    finally:
-        con.close()
+    cached = _compute_cached_map(settings)
+    payload = {
+        "views": {
+            name: [{"column": c, "type": t} for c, t in cols] for name, cols in VIEW_SCHEMA.items()
+        },
+        "macros": [{"name": n, "params": list(p)} for n, p in MACRO_SIGNATURES.items()],
+        "cached": cached,
+    }
+    if fmt is OutputFormat.TABLE:
+        for name, cols in VIEW_SCHEMA.items():
+            print(f"\n\033[1m{name}\033[0m ({len(cols)} cols)")
+            for col, col_type in cols:
+                print(f"  {col:<28} {col_type}")
+        print(f"\n\033[1mMacros\033[0m ({len(MACRO_SIGNATURES)})")
+        for n, params in MACRO_SIGNATURES.items():
+            tag = "" if cached.get(n, True) else "  [cache empty]"
+            print(f"  {n}({', '.join(params)}){tag}")
+        return
+    emit_json(payload, fmt)
 
 
 @app.command(name="list-cache")
@@ -1173,7 +1285,7 @@ def search(
     _configure(common)
     settings = _resolve_settings(common)
     fmt = _fmt(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         row = con.execute("SELECT count(*) FROM message_embeddings").fetchone()
         count = int(row[0]) if row else 0
@@ -1263,7 +1375,7 @@ def classify(
     """
     _configure(common)
     settings = _resolve_settings(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         result = classify_sessions(
             con,
@@ -1311,7 +1423,7 @@ def trajectory(
     """
     _configure(common)
     settings = _resolve_settings(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         result = trajectory_messages(
             con,
@@ -1355,7 +1467,7 @@ def conflicts(
     """
     _configure(common)
     settings = _resolve_settings(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         result = detect_conflicts(
             con,
@@ -1405,7 +1517,7 @@ def friction(
     """
     _configure(common)
     settings = _resolve_settings(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         result = detect_user_friction(
             con,
@@ -1472,7 +1584,7 @@ def terms(*, force: bool = False, common: Common | None = None) -> None:
     """
     _configure(common)
     settings = _resolve_settings(common)
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         tstats = run_terms(con, settings, force=force)
         logger.info(
@@ -1560,7 +1672,7 @@ def community(
         emit_error(err, fmt)
         sys.exit(err.exit_code)
 
-    con = _open_connection(settings)
+    con = _open_connection_full(settings)
     try:
         if neighbors_of_session is not None:
             df = neighbors_of(con, settings, neighbors_of_session, top_k=top_k)
@@ -1704,7 +1816,7 @@ def analyze(
 
     # 1. Embed (reuses embed_worker).  Silently skipped if the parquet is up to date.
     if not skip_embed:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             n = asyncio.run(
                 run_backfill(
@@ -1728,7 +1840,7 @@ def analyze(
             stats["clusters"],
             stats["noise"],
         )
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             tstats = run_terms(con, settings, force=force_cluster)
             logger.info(
@@ -1741,7 +1853,7 @@ def analyze(
 
     # 3. Community detection (non-LLM, runs in parallel conceptually with cluster).
     if not skip_community:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             cstats = run_communities(con, settings, force=force_community)
             logger.info(
@@ -1754,7 +1866,7 @@ def analyze(
 
     # 4. Session classification (LLM).
     if not skip_classify:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             n = classify_sessions(
                 con,
@@ -1770,7 +1882,7 @@ def analyze(
 
     # 5. Trajectory (LLM).
     if not skip_trajectory:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             n = trajectory_messages(
                 con,
@@ -1786,7 +1898,7 @@ def analyze(
 
     # 6. Conflicts (LLM, requires full session context).
     if not skip_conflicts:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             n = detect_conflicts(
                 con,
@@ -1802,7 +1914,7 @@ def analyze(
 
     # 7. Friction (LLM, short-message scope).
     if not skip_friction:
-        con = _open_connection(settings)
+        con = _open_connection_full(settings)
         try:
             n = detect_user_friction(
                 con,
@@ -2297,19 +2409,33 @@ def resolve_cmd(
     emit_json(binding.to_dict(), fmt=fmt)
 
 
-def _review_sheet_format(common: Common | None) -> OutputFormat:
-    """Pick the review-sheet effective format.
+class RenderFormat(StrEnum):
+    """``review-sheet`` render targets.
+
+    Local to ``review-sheet`` because no other subcommand emits human prose.
+    Keeping markdown out of the global :class:`OutputFormat` keeps
+    ``--format`` honest on every other subcommand (only renderers that
+    actually support markdown get to advertise it).
+    """
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+
+
+def _review_sheet_format(common: Common | None) -> RenderFormat:
+    """Pick the review-sheet effective render format.
 
     Default policy diverges from every other subcommand: review-sheet
-    output is human-first prose, so ``AUTO`` resolves to ``MARKDOWN`` on
-    a TTY (override of the global ``TABLE`` default) and ``JSON``
-    off-TTY. Explicit ``--format`` flags pass through unchanged so
-    agents can still pin ``--format json`` regardless of TTY state.
+    output is human-first prose, so ``--format auto`` resolves to
+    ``MARKDOWN`` on a TTY (override of the global ``TABLE`` default) and
+    ``JSON`` off-TTY. ``--format json`` always pins JSON; every other
+    ``OutputFormat`` value resolves to ``MARKDOWN`` on a TTY and ``JSON``
+    off-TTY (table/ndjson/csv are not meaningful for the prose shape).
     """
     fmt = _fmt(common)
-    if fmt is not OutputFormat.AUTO:
-        return fmt
-    return OutputFormat.MARKDOWN if sys.stdout.isatty() else OutputFormat.JSON
+    if fmt is OutputFormat.JSON:
+        return RenderFormat.JSON
+    return RenderFormat.MARKDOWN if sys.stdout.isatty() else RenderFormat.JSON
 
 
 @app.command(name="review-sheet")
@@ -2355,6 +2481,9 @@ def review_sheet_cmd(
     """
     _configure(common)
     fmt = _review_sheet_format(common)
+    # Error output follows the global rule (TABLE on TTY, JSON off-TTY) — the
+    # render format is only meaningful for the success-path narrative.
+    error_fmt = _fmt(common)
     settings = _resolve_settings(common)
     repo_path = repo.resolve() if repo is not None else None
 
@@ -2371,7 +2500,7 @@ def review_sheet_cmd(
             message=str(exc),
             hint="run `claude-sql resolve <sha> --all-sources` to see both surfaces",
         )
-        emit_error(err, fmt)
+        emit_error(err, error_fmt)
         sys.exit(err.exit_code)
     except LookupError as exc:
         err = ClassifiedError(
@@ -2380,7 +2509,7 @@ def review_sheet_cmd(
             message=str(exc),
             hint="commit has no Claude-Transcript-* trailer and no refs/notes/transcripts entry",
         )
-        emit_error(err, fmt)
+        emit_error(err, error_fmt)
         sys.exit(err.exit_code)
     except _binding.GitInvocationError as exc:
         err = ClassifiedError(
@@ -2389,7 +2518,7 @@ def review_sheet_cmd(
             message=f"git invocation failed: {exc.stderr.strip()}",
             hint="check that the commit SHA exists in --repo",
         )
-        emit_error(err, fmt)
+        emit_error(err, error_fmt)
         sys.exit(err.exit_code)
 
     # Hand the resolved URI through the override so the worker doesn't
@@ -2412,19 +2541,19 @@ def review_sheet_cmd(
         return
 
     if result.get("refused"):
-        if fmt is OutputFormat.MARKDOWN:
+        if fmt is RenderFormat.MARKDOWN:
             metadata = result.get("metadata") or {"commit_sha": commit_sha}
             print(render_refusal_markdown(str(result.get("reason", "")), metadata))
             return
-        emit_json(result, fmt=fmt)
+        emit_json(result, fmt=OutputFormat.JSON)
         return
 
     sheet = result.get("sheet") or {}
     metadata = result.get("metadata") or {}
-    if fmt is OutputFormat.MARKDOWN:
+    if fmt is RenderFormat.MARKDOWN:
         print(render_markdown(sheet, metadata))
         return
-    emit_json({"sheet": sheet, "metadata": metadata}, fmt=fmt)
+    emit_json({"sheet": sheet, "metadata": metadata}, fmt=OutputFormat.JSON)
 
 
 @app.default

{claude_sql-0.5.0 → claude_sql-0.6.0}/src/claude_sql/config.py

@@ -312,7 +312,8 @@ class Settings(BaseSettings):
     tfidf_top_n_terms: int = 10
 
     # ------------------------------------------------------------------
-    # DuckDB engine tuning — applied as PRAGMAs in cli._open_connection.
+    # DuckDB engine tuning — applied as PRAGMAs in cli._open_connection_full
+    # and cli._open_connection_introspect.
     # ------------------------------------------------------------------
     #: Worker threads. Defaults to ``os.cpu_count()`` so DuckDB uses every
     #: core; agents and CI runners with limited parallelism can override.

{claude_sql-0.5.0 → claude_sql-0.6.0}/src/claude_sql/output.py

@@ -24,11 +24,17 @@ import polars as pl
 
 
 class OutputFormat(StrEnum):
-    """Supported output formats.
+    """Supported output formats for tabular and structured CLI output.
 
     ``AUTO`` resolves to ``TABLE`` when stdout is a TTY and ``JSON`` otherwise.
     Keeping it a string Enum lets cyclopts parse ``--format json`` without any
     custom converter.
+
+    Markdown rendering is intentionally absent: only ``review-sheet`` emits
+    human prose, and it owns its own ``--render`` flag (see
+    :class:`claude_sql.cli.RenderFormat`). Pulling markdown into this enum
+    advertised the format on every subcommand even though no other command
+    knows how to produce it.
     """
 
     AUTO = "auto"
@@ -36,7 +42,6 @@ class OutputFormat(StrEnum):
     JSON = "json"
     NDJSON = "ndjson"
     CSV = "csv"
-    MARKDOWN = "markdown"
 
 
 # Exit codes that agents can rely on.  Keep them stable -- wire protocols
@@ -98,8 +103,9 @@ def emit_dataframe(
     if resolved is OutputFormat.CSV:
         df.write_csv(sys.stdout)
         return
-    # unreachable if OutputFormat stays closed-set
-    raise ValueError(f"Unsupported format: {resolved}")
+    # Defensive: unreachable while OutputFormat stays closed-set
+    # (auto/table/json/ndjson/csv). Kept as a guard for future enum additions.
+    raise ValueError(f"Unsupported format: {resolved}")  # pragma: no cover
 
 
 def emit_json(payload: Any, fmt: OutputFormat | str = OutputFormat.AUTO) -> None: