roam-code 12.3.0__tar.gz → 12.4.0__tar.gz

{roam_code-12.3.0/src/roam_code.egg-info → roam_code-12.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roam-code
-Version: 12.3.0
+Version: 12.4.0
 Summary: Instant codebase comprehension for AI coding agents
 Author: CosmoHac
 License-Expression: MIT

{roam_code-12.3.0 → roam_code-12.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "roam-code"
-version = "12.3.0"
+version = "12.4.0"
 description = "Instant codebase comprehension for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/catalog/detectors.py

@@ -2300,6 +2300,17 @@ def _iter_registered_detectors():
     for det in _MATH_DETECTORS:
         yield det
 
+    # Python pivot v12.4 — language-specific idiom detectors. Wrapped
+    # in try/except so a regex bug in one detector can't block the
+    # algorithm pass.
+    try:
+        from roam.catalog.python_idioms import PYTHON_IDIOM_DETECTORS
+
+        for det in PYTHON_IDIOM_DETECTORS:
+            yield det
+    except Exception:
+        pass
+
     try:
         from roam.plugins import get_plugin_detectors
 

roam_code-12.4.0/src/roam/catalog/python_idioms.py

@@ -0,0 +1,273 @@
+"""Python-specific anti-pattern detectors.
+
+Surfaced in v12.4 from the Python-pivot dogfood (2026-05-02). The
+existing ``catalog/detectors.py`` covers language-agnostic algorithm
+patterns (O(n²) string concat, sort-to-take, IO-in-loop). This module
+adds Python-canonical anti-patterns that don't generalise to other
+languages and would muddy the detector registry there.
+
+Each detector returns a list of ``(symbol_id, pattern_id, severity,
+description, fix_hint)`` tuples — same shape as the algorithm
+detectors so they plug into the same ``roam math`` / ``roam smells``
+plumbing.
+
+Initial detectors (most-cited Python footguns):
+
+1. **Mutable default argument** — ``def foo(x=[])`` / ``def bar(d={})``.
+   The list/dict is created *once* at definition time and shared
+   across calls. Classic source of "why does my list keep growing?".
+2. **Bare except** — ``except:`` with no exception type. Catches
+   ``SystemExit`` and ``KeyboardInterrupt``, masking critical
+   shutdown signals. PEP 8 explicitly discourages this.
+3. **Comparison to None with ``==``** — should use ``is None``.
+   Not just style: ``__eq__`` overrides can do anything.
+4. **f-string in logger calls** — ``logger.info(f"x={x}")`` evaluates
+   the format string even if the log level is below INFO. Use
+   ``logger.info("x=%s", x)`` for lazy evaluation.
+
+Detectors are line-anchored regex over the source text rather than
+AST queries because Python's tree-sitter grammar exposes default
+argument values as a deeply-nested chain that's brittle to query.
+The regex approach is "good enough" for these specific patterns and
+ports trivially to YAML/Jupyter notebooks if we extend later.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+
+# ---------------------------------------------------------------------------
+# Pattern regexes (compiled once)
+# ---------------------------------------------------------------------------
+
+# def foo(x=[]) — also matches dict, set literal, function calls like list()
+# Skips ``=None`` and immutable literals (``=0``, ``=""``, ``=()``).
+_MUTABLE_DEFAULT_RE = re.compile(
+    r"def\s+\w+\s*\([^)]*?(\w+)\s*=\s*"
+    r"(\[\s*\]|\{\s*\}|\{\s*[^}:]+\s*\}|list\(\s*\)|dict\(\s*\)|set\(\s*\))",
+)
+
+# bare except — matches ``except:`` with optional whitespace,
+# but NOT ``except SomeError:`` or ``except (A, B):``.
+_BARE_EXCEPT_RE = re.compile(r"^\s*except\s*:", re.MULTILINE)
+
+# == None or != None at end-of-expression positions. The leading
+# ``\b`` doesn't apply (operators aren't word chars); we anchor on
+# the comparison operator and require ``None`` followed by a non-word
+# character to avoid matching ``Nonetype`` etc.
+_NONE_EQ_RE = re.compile(r"(==|!=)\s*None\b")
+
+# logger.<level>(f"..."): logger / log / logging variants
+_LOGGER_FSTRING_RE = re.compile(
+    r"\b(?:logger|log|logging|self\.logger|self\.log)\.(?:debug|info|warning|warn|error|critical|exception)\s*\(\s*f[\"']",
+)
+
+
+def _file_text(conn: sqlite3.Connection, file_id: int) -> str | None:
+    """Read the source text of a file via roam.index — but the index
+    doesn't store source. Instead we read from disk via the file path.
+    Fast (mmap) and safe to no-op on read errors.
+    """
+    row = conn.execute("SELECT path FROM files WHERE id = ?", (file_id,)).fetchone()
+    if row is None:
+        return None
+    path = row[0]
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except OSError:
+        return None
+
+
+def _python_files(conn: sqlite3.Connection) -> list[tuple[int, str]]:
+    """Return ``(file_id, path)`` for every Python file in the index."""
+    return [(int(r[0]), r[1]) for r in conn.execute("SELECT id, path FROM files WHERE language = 'python'").fetchall()]
+
+
+def _line_to_symbol(conn: sqlite3.Connection, file_id: int) -> list[tuple[int, int, int, str]]:
+    """``(symbol_id, line_start, line_end, name)`` for symbols in
+    ``file_id`` ordered by line. Used to attribute regex matches to
+    the enclosing symbol."""
+    return [
+        (int(r[0]), int(r[1] or 0), int(r[2] or 0), r[3])
+        for r in conn.execute(
+            "SELECT id, line_start, line_end, name FROM symbols WHERE file_id = ? ORDER BY line_start",
+            (file_id,),
+        ).fetchall()
+    ]
+
+
+def _enclosing_symbol(line_no: int, sym_index: list[tuple[int, int, int, str]]) -> tuple[int, str] | None:
+    """Return the innermost ``(symbol_id, name)`` whose line range
+    contains ``line_no``, or ``None``. Innermost = max line_start."""
+    best: tuple[int, str] | None = None
+    best_start = -1
+    for sid, start, end, name in sym_index:
+        if start <= line_no <= end and start > best_start:
+            best = (sid, name)
+            best_start = start
+    return best
+
+
+# ---------------------------------------------------------------------------
+# Detectors
+# ---------------------------------------------------------------------------
+
+
+def _idiom_finding(
+    *,
+    task_id: str,
+    detected_way: str,
+    symbol_id: int,
+    symbol_name: str,
+    file_path: str,
+    line_no: int,
+    reason: str,
+    confidence: str = "high",
+    fix: str | None = None,
+) -> dict:
+    """Build a finding dict in the shape ``catalog.detectors._finding``
+    produces, so the same downstream calibration / display works."""
+    return {
+        "task_id": task_id,
+        "detected_way": detected_way,
+        "suggested_way": detected_way,
+        "symbol_id": symbol_id,
+        "symbol_name": symbol_name,
+        "kind": "function",
+        "location": f"{file_path}:{line_no}",
+        "confidence": confidence,
+        "reason": reason,
+        "fix": fix or "",
+    }
+
+
+def detect_mutable_default_arg(conn: sqlite3.Connection) -> list[dict]:
+    """Find ``def foo(x=[])`` / ``def foo(d={})`` patterns."""
+    findings: list[dict] = []
+    for file_id, path in _python_files(conn):
+        text = _file_text(conn, file_id)
+        if not text:
+            continue
+        sym_index = _line_to_symbol(conn, file_id)
+        for match in _MUTABLE_DEFAULT_RE.finditer(text):
+            line_no = text.count("\n", 0, match.start()) + 1
+            sym = _enclosing_symbol(line_no, sym_index)
+            if sym is None:
+                continue
+            param = match.group(1)
+            findings.append(
+                _idiom_finding(
+                    task_id="py-mutable-default-arg",
+                    detected_way="default-mutable",
+                    symbol_id=sym[0],
+                    symbol_name=sym[1],
+                    file_path=path,
+                    line_no=line_no,
+                    reason=(f"Mutable default arg: ``{param}={match.group(2)}`` is shared across calls"),
+                    confidence="high",
+                    fix=f"def fn({param}=None): ...; if {param} is None: {param} = [] / {{}} / set()",
+                )
+            )
+    return findings
+
+
+def detect_bare_except(conn: sqlite3.Connection) -> list[dict]:
+    """Find ``except:`` (no exception type)."""
+    findings: list[dict] = []
+    for file_id, path in _python_files(conn):
+        text = _file_text(conn, file_id)
+        if not text:
+            continue
+        sym_index = _line_to_symbol(conn, file_id)
+        for match in _BARE_EXCEPT_RE.finditer(text):
+            line_no = text.count("\n", 0, match.start()) + 1
+            sym = _enclosing_symbol(line_no, sym_index)
+            if sym is None:
+                continue
+            findings.append(
+                _idiom_finding(
+                    task_id="py-bare-except",
+                    detected_way="catch-all",
+                    symbol_id=sym[0],
+                    symbol_name=sym[1],
+                    file_path=path,
+                    line_no=line_no,
+                    reason="bare ``except:`` catches SystemExit/KeyboardInterrupt — shutdown signals masked",
+                    confidence="high",
+                    fix="except Exception:  # or the specific class you mean to handle",
+                )
+            )
+    return findings
+
+
+def detect_none_eq(conn: sqlite3.Connection) -> list[dict]:
+    """Find ``x == None`` / ``x != None``."""
+    findings: list[dict] = []
+    for file_id, path in _python_files(conn):
+        text = _file_text(conn, file_id)
+        if not text:
+            continue
+        sym_index = _line_to_symbol(conn, file_id)
+        for match in _NONE_EQ_RE.finditer(text):
+            line_no = text.count("\n", 0, match.start()) + 1
+            sym = _enclosing_symbol(line_no, sym_index)
+            if sym is None:
+                continue
+            op = match.group(1)
+            replacement = "is" if op == "==" else "is not"
+            findings.append(
+                _idiom_finding(
+                    task_id="py-none-eq",
+                    detected_way="eq-not-is",
+                    symbol_id=sym[0],
+                    symbol_name=sym[1],
+                    file_path=path,
+                    line_no=line_no,
+                    reason=f"``{op} None`` invokes ``__eq__``; use ``{replacement} None`` (idiomatic, faster)",
+                    confidence="medium",
+                    fix=f"x {replacement} None",
+                )
+            )
+    return findings
+
+
+def detect_logger_fstring(conn: sqlite3.Connection) -> list[dict]:
+    """Find ``logger.info(f"...")`` — eager-format anti-pattern."""
+    findings: list[dict] = []
+    for file_id, path in _python_files(conn):
+        text = _file_text(conn, file_id)
+        if not text:
+            continue
+        sym_index = _line_to_symbol(conn, file_id)
+        for match in _LOGGER_FSTRING_RE.finditer(text):
+            line_no = text.count("\n", 0, match.start()) + 1
+            sym = _enclosing_symbol(line_no, sym_index)
+            if sym is None:
+                continue
+            findings.append(
+                _idiom_finding(
+                    task_id="py-logger-fstring",
+                    detected_way="eager-format",
+                    symbol_id=sym[0],
+                    symbol_name=sym[1],
+                    file_path=path,
+                    line_no=line_no,
+                    reason="f-string in logger call evaluates even when level discards the message",
+                    confidence="high",
+                    fix='logger.info("x=%s", x)',
+                )
+            )
+    return findings
+
+
+# Detector registry — same shape ``cmd_math`` expects from ``_MATH_DETECTORS``
+# (task_id, pattern_id, detect_fn). Re-exported so registration is one
+# import line elsewhere.
+PYTHON_IDIOM_DETECTORS = [
+    ("py-mutable-default-arg", "default-mutable", detect_mutable_default_arg),
+    ("py-bare-except", "catch-all", detect_bare_except),
+    ("py-none-eq", "eq-not-is", detect_none_eq),
+    ("py-logger-fstring", "eager-format", detect_logger_fstring),
+]

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_complexity.py

@@ -67,8 +67,19 @@ def _severity_icon(sev: str) -> str:
     is_flag=True,
     help="Detect bumpy-road pattern: files with multiple medium-complexity functions",
 )
+@click.option(
+    "--include-tooling",
+    is_flag=True,
+    default=False,
+    help=(
+        "Include CI scripts, examples, generated code, vendor, and "
+        "workspaces directories. Excluded by default — high complexity "
+        "in tooling/codegen is expected and uninteresting (Python pivot "
+        "dogfood 2026-05-02 found agent-generated workspaces dominating)."
+    ),
+)
 @click.pass_context
-def complexity(ctx, target, limit, threshold, by_file, bumpy_road):
+def complexity(ctx, target, limit, threshold, by_file, bumpy_road, include_tooling):
     """Show cognitive complexity metrics for functions and methods.
 
     Unlike ``health`` (which scores the whole codebase) and ``debt`` (which
@@ -117,6 +128,10 @@ def complexity(ctx, target, limit, threshold, by_file, bumpy_road):
 
         where_clause = " AND ".join(where_parts) if where_parts else "1=1"
 
+        # Pull more rows than ``limit`` when default-excluding tooling
+        # so the displayed top-N still has the requested count after
+        # filtering. 5x is comfortable for typical exclusion shares.
+        fetch_limit = limit * 5 if not include_tooling else limit
         rows = conn.execute(
             f"""SELECT sm.*, s.name, s.qualified_name, s.kind,
                        s.line_start, s.line_end, f.path as file_path
@@ -126,8 +141,13 @@ def complexity(ctx, target, limit, threshold, by_file, bumpy_road):
                 WHERE {where_clause}
                 ORDER BY sm.cognitive_complexity DESC
                 LIMIT ?""",
-            params + [limit],
+            params + [fetch_limit],
         ).fetchall()
+        if not include_tooling:
+            from roam.output.file_role_hints import is_excluded_path
+
+            rows = [r for r in rows if not is_excluded_path(r["file_path"] or "")]
+            rows = rows[:limit]
 
         if not rows:
             if sarif_mode:

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_context.py

@@ -523,6 +523,17 @@ def _render_single_text(data):
     click.echo(f"VERDICT: {verdict}")
     click.echo()
     click.echo(f"=== Context for: {sym['name']}{task_suffix} ===")
+    # Python pivot v12.4: surface async + decorators above the
+    # signature so agents reading context know coroutine semantics
+    # without scanning source. ``sym`` is a sqlite3.Row which doesn't
+    # expose ``.get`` — guard each access with a key check.
+    _row_keys = sym.keys() if hasattr(sym, "keys") else []
+    if "is_async" in _row_keys and sym["is_async"]:
+        click.echo("  [async coroutine]")
+    decorators_str = (sym["decorators"] if "decorators" in _row_keys else "") or ""
+    if decorators_str:
+        for d in decorators_str.split(",")[:5]:
+            click.echo(f"  {d.strip()}")
     click.echo(
         f"{abbrev_kind(sym['kind'])}  "
         f"{sym['qualified_name'] or sym['name']}"

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_dead.py

@@ -358,17 +358,7 @@ def _group_dead(dead_items, by):
 # ---------------------------------------------------------------------------
 
 
-_TOOLING_PATH_HINTS = ("/dev/", "/benchmarks/", "/.github/", "\\dev\\", "\\benchmarks\\", "\\.github\\")
-
-
-def _is_tooling_path(path: str) -> bool:
-    """Same hint set as cmd_fan / cmd_smells. Excluded from dead-code
-    headline by default (dogfood notes 2026-05-01) — CI scripts are
-    expected to have unreferenced helper functions."""
-    if not path:
-        return False
-    p = "/" + path.replace("\\", "/")
-    return any(hint.replace("\\", "/") in p for hint in _TOOLING_PATH_HINTS)
+from roam.output.file_role_hints import is_excluded_path as _is_tooling_path
 
 
 def _analyze_dead(conn):
@@ -1114,6 +1104,7 @@ def dead(
                 return
             if json_mode:
                 summary = {
+                    "verdict": "no dead exports",
                     "safe": 0,
                     "review": 0,
                     "intentional": 0,
@@ -1281,7 +1272,14 @@ def dead(
                     d["decay_score"] = ext["decay_score"]
                 return d
 
+            total = n_safe + n_review + n_intent
+            verdict = (
+                f"{total} dead export(s): {n_safe} safe, {n_review} review, {n_intent} intentional"
+                if total
+                else "no dead exports"
+            )
             summary = {
+                "verdict": verdict,
                 "safe": n_safe,
                 "review": n_review,
                 "intentional": n_intent,

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_fan.py

@@ -107,25 +107,17 @@ _FRAMEWORK_NAMES = frozenset(
 )
 
 
-_TOOLING_PATH_HINTS = ("/dev/", "/benchmarks/", "/.github/", "\\dev\\", "\\benchmarks\\", "\\.github\\")
+from roam.output.file_role_hints import is_excluded_path
 
 
-def _is_tooling_path(path: str) -> bool:
-    """Return True for paths that belong to tooling/CI/benchmarks/dev.
+def _filter_tooling_rows(rows):
+    """Filter out rows whose ``file_path`` is in a default-excluded
+    location (tooling, generated, examples, vendor, workspaces, etc.).
 
-    Default-excluded from headline metrics so first-time users aren't
-    dominated by ``pr-comment.js`` and ``roam-bench.py`` rows.
-    Matches the hint set used by ``cmd_smells._file_role_lookup``.
+    Uses the shared ``output.file_role_hints`` set so all headline
+    commands stay in sync.
     """
-    if not path:
-        return False
-    p = "/" + path.replace("\\", "/")
-    return any(hint.replace("\\", "/") in p for hint in _TOOLING_PATH_HINTS)
-
-
-def _filter_tooling_rows(rows):
-    """Filter out rows whose ``file_path`` is in a tooling location."""
-    return [r for r in rows if not _is_tooling_path(r["file_path"] or "")]
+    return [r for r in rows if not is_excluded_path(r["file_path"] or "")]
 
 
 @click.command()

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_retrieve.py

@@ -49,8 +49,19 @@ def _retrieve_confidence(candidates: list[dict], task: str = "") -> str:
     if not scores:
         return "ok"
 
-    # Score-based check
+    # High-confidence override (dogfood R14 2026-05-01): a top-1 that
+    # significantly outranks the 2nd hit (gap ≥ 0.30 in normalised
+    # space) signals a unique winner — the structural reranker found
+    # one strong answer rather than many equal candidates. Skip the
+    # token-coverage check in that case.
+    # Distinguishes the email query ("where is email sending" →
+    # send_welcome at 0.900, 2nd at 0.275 → gap 0.625, real answer)
+    # from the trace query ("trace the login flow" → 1.014, 2nd 0.942
+    # → gap 0.072, all matching one common word).
     top = scores[0]
+    second = scores[1] if len(scores) > 1 else 0.0
+    if top - second >= 0.30:
+        return "ok"
     fifth = scores[min(4, len(scores) - 1)]
     if top < 0.30 and (top - fifth) < 0.10:
         return "low"

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_search.py

@@ -160,9 +160,25 @@ def _format_explanation_text(expl: dict) -> list[str]:
     default=None,
     help="Filter by symbol kind (fn, cls, meth, var, iface, etc.)",
 )
+@click.option(
+    "--async",
+    "async_only",
+    is_flag=True,
+    help="Show only async functions/methods (requires Python pivot v12.4 schema).",
+)
+@click.option(
+    "--decorator",
+    "decorator_filter",
+    default=None,
+    help=(
+        "Filter to symbols carrying a decorator matching this substring "
+        "(case-insensitive). E.g. ``--decorator pytest.fixture`` finds all "
+        "fixtures. ``--decorator app.route`` finds Flask/FastAPI routes."
+    ),
+)
 @click.option("--explain", is_flag=True, help="Show score breakdown for each result")
 @click.pass_context
-def search(ctx, pattern, full, kind_filter, explain):
+def search(ctx, pattern, full, kind_filter, async_only, decorator_filter, explain):
     """Find symbols matching a name substring (case-insensitive).
 
     Unlike ``grep`` (which searches file contents) and ``search-semantic``
@@ -180,6 +196,12 @@ def search(ctx, pattern, full, kind_filter, explain):
             abbrev_to_kind = {v: k for k, v in KIND_ABBREV.items()}
             full_kind = abbrev_to_kind.get(kind_filter, kind_filter)
             rows = [r for r in rows if r["kind"] == full_kind]
+        # Python pivot v12.4 — filter by async/decorator
+        if async_only:
+            rows = [r for r in rows if (r["is_async"] if "is_async" in r.keys() else 0)]
+        if decorator_filter:
+            needle = decorator_filter.lower()
+            rows = [r for r in rows if needle in (r["decorators"] or "").lower()]
 
         if not rows:
             suffix = f" of kind '{kind_filter}'" if kind_filter else ""

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/commands/cmd_smells.py

@@ -93,16 +93,20 @@ def smells(ctx, file_path, min_severity, include_tooling):
     with open_db(readonly=True) as conn:
         findings = run_all_detectors(conn)
 
-        # Default: exclude tooling. Per dogfood notes 2026-05-01, the
-        # top-N critical smells were dominated by .github/scripts,
-        # benchmarks/, dev/, and generated files — none of which are
-        # source code a user would want to refactor. Their inclusion
-        # made the verdict ("Needs refactoring: 1689 smells") false-
-        # alarming. ``--include-tooling`` opts back into the full set.
+        # Default: exclude tooling, generated, examples, vendor, workspaces,
+        # docs. Per dogfood notes 2026-05-01 + 2026-05-02 (Python pivot),
+        # the top-N critical smells were dominated by paths the user
+        # didn't write or doesn't want to refactor (``dev/``,
+        # ``.github/scripts/``, ``examples/``, ``workspaces/`` agent
+        # artifacts, vendored packages, codegen output). The shared
+        # path-hint set lives in ``roam.output.file_role_hints`` so all
+        # headline commands stay in sync. ``--include-tooling`` opts
+        # back into the full set.
+        from roam.output.file_role_hints import is_excluded_path
+
         excluded_tooling = 0
         if not include_tooling:
             tooling_roles = {"ci", "scripts", "build", "generated"}
-            tooling_path_hints = ("/dev/", "/benchmarks/", "/.github/", "\\dev\\", "\\benchmarks\\", "\\.github\\")
             tooling_roles_per_file = _file_role_lookup(conn)
             kept: list[dict] = []
             for f in findings:
@@ -112,7 +116,7 @@ def smells(ctx, file_path, min_severity, include_tooling):
                 if role in tooling_roles:
                     excluded_tooling += 1
                     continue
-                if any(hint.replace("\\", "/") in "/" + file_path_only for hint in tooling_path_hints):
+                if is_excluded_path(file_path_only):
                     excluded_tooling += 1
                     continue
                 kept.append(f)

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/db/connection.py

@@ -146,6 +146,9 @@ def ensure_schema(conn: sqlite3.Connection):
 
     # Migrations for columns added after initial schema
     _safe_alter(conn, "symbols", "default_value", "TEXT")
+    # Python pivot v12.4: is_async + decorators on symbols
+    _safe_alter(conn, "symbols", "is_async", "INTEGER DEFAULT 0")
+    _safe_alter(conn, "symbols", "decorators", "TEXT DEFAULT ''")
     _safe_alter(conn, "file_stats", "health_score", "REAL")
     _safe_alter(conn, "file_stats", "cochange_entropy", "REAL")
     _safe_alter(conn, "file_stats", "cognitive_load", "REAL")

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/db/schema.py

@@ -24,7 +24,15 @@ CREATE TABLE IF NOT EXISTS symbols (
     visibility TEXT DEFAULT 'public',
     is_exported INTEGER DEFAULT 1,
     parent_id INTEGER REFERENCES symbols(id) ON DELETE SET NULL,
-    default_value TEXT
+    default_value TEXT,
+    -- Python pivot v12.4: is_async marks ``async def`` functions/methods.
+    -- Lets agents distinguish coroutines from sync calls without
+    -- regex'ing the source. Used by retrieve, context, search.
+    is_async INTEGER DEFAULT 0,
+    -- Decorators applied to the symbol, comma-joined ("@property,@cached").
+    -- Empty when none. Captured by the Python extractor; other languages
+    -- may populate when the concept maps (TypeScript decorators).
+    decorators TEXT DEFAULT ''
 );
 
 CREATE TABLE IF NOT EXISTS edges (

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/index/indexer.py

@@ -429,8 +429,9 @@ def _store_symbols(conn, file_id, rel_path, symbols, all_symbol_rows):
             """INSERT INTO symbols
                (file_id, name, qualified_name, kind, signature,
                 line_start, line_end, docstring, visibility,
-                is_exported, parent_id, default_value)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                is_exported, parent_id, default_value,
+                is_async, decorators)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
             (
                 file_id,
                 sym["name"],
@@ -444,6 +445,8 @@ def _store_symbols(conn, file_id, rel_path, symbols, all_symbol_rows):
                 1 if sym["is_exported"] else 0,
                 parent_id,
                 sym.get("default_value"),
+                1 if sym.get("is_async") else 0,
+                sym.get("decorators") or "",
             ),
         )
         row = conn.execute("SELECT last_insert_rowid()").fetchone()

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/index/symbols.py

@@ -20,7 +20,10 @@ def extract_symbols(tree, source: bytes, file_path: str, extractor) -> list[dict
     except Exception:
         return []
 
-    # Ensure every symbol dict has all required keys with defaults
+    # Ensure every symbol dict has all required keys with defaults.
+    # Python pivot v12.4 added ``is_async`` and ``decorators`` — they
+    # must pass through this normalisation or the indexer never sees
+    # them (caught by dogfood notes 2026-05-02 R3).
     normalised = []
     for sym in symbols:
         normalised.append(
@@ -36,6 +39,8 @@ def extract_symbols(tree, source: bytes, file_path: str, extractor) -> list[dict
                 "is_exported": sym.get("is_exported", True),
                 "parent_name": sym.get("parent_name"),
                 "default_value": sym.get("default_value"),
+                "is_async": bool(sym.get("is_async", False)),
+                "decorators": sym.get("decorators") or "",
             }
         )
     return normalised

{roam_code-12.3.0 → roam_code-12.4.0}/src/roam/languages/base.py

@@ -74,6 +74,8 @@ class LanguageExtractor(ABC):
         is_exported: bool = False,
         parent_name: str | None = None,
         default_value: str | None = None,
+        is_async: bool = False,
+        decorators: str = "",
     ) -> dict:
         return {
             "name": name,
@@ -87,6 +89,8 @@ class LanguageExtractor(ABC):
             "is_exported": is_exported,
             "parent_name": parent_name,
             "default_value": default_value,
+            "is_async": bool(is_async),
+            "decorators": decorators or "",
         }
 
     def _make_reference(