Review: Full codebase audit via Greptile

[Gradata]

Purpose

Trigger Greptile's automated review on the full v0.3.0 codebase.

This is a test PR to evaluate Greptile's review quality against our own internal review pipeline (autoresearch + simplify + security audit + adversary).

What to review

• src/gradata/ — full SDK
• src/gradata/hooks/ — nervous system hooks
• tests/ — test suite

After review

Compare Greptile findings vs our own. Delete this PR either way.

Generated with Gradata

Greptile Summary

This PR adds a single greptile-review.md trigger file as a test of Greptile's review quality against the team's internal pipeline, auditing the full v0.3.0 "Nervous System" release.

The new EventBus design (events_bus.py) is well-implemented — handler failures are correctly isolated via _safe_call, listener count is bounded at 50, async handlers use a bounded thread pool, and the integration test (test_bus_error_isolation) verifies that a crashing subscriber does not interrupt the correction pipeline. The dual-write event persistence in _events.py (JSONL + SQLite with WAL mode) is solid.

Key findings from the audit:

• Multi-brain ctx gap (_events.py): supersede(), correction_rate(), compute_leading_indicators(), and audit_trend() bypass the BrainContext injection that emit() and query() support, silently routing all calls to the global _p.DB_PATH. Any user running two Brain instances in a single process will encounter silent cross-brain data corruption on these four code paths.
• print() instead of logging (Rule 1): Eight production sites across _events.py, rules/rule_tracker.py, mcp_server.py, and _embed.py use print(..., file=sys.stderr) for error and warning messages, making them invisible to callers that use structured logging.
• Missing from __future__ import annotations (Rule 6): Six SDK modules (_paths.py, _doctor.py, _embed.py, cli.py, _installer.py, _validator.py) are missing the required future import despite using union-type annotations (str | Path | None)."

Confidence Score: 4/5

Codebase is structurally sound with 1339 passing tests; the ctx-gap and logging violations are clean-up items that do not affect single-brain users.

EventBus error isolation is correctly implemented and tested. The main issues are: (1) a multi-brain isolation bug in four _events.py functions that only affects multi-Brain processes, (2) print() logging violations across 4 files, and (3) missing future imports in 6 files. None of these block single-brain functionality. Score is 4 rather than 5 because the ctx-gap in supersede() is a real silent-data-corruption risk for any user running two Brain instances simultaneously.

src/gradata/_events.py (ctx-gap + logging violations), src/gradata/rules/rule_tracker.py (print logging), src/gradata/mcp_server.py (print logging), and the six SDK modules missing from future import annotations

Important Files Changed

Filename	Overview
src/gradata/_events.py	Core event persistence layer; two print() logging violations and four ctx-unaware functions break multi-brain isolation
src/gradata/_paths.py	Path resolution module; missing from future import annotations despite using union type syntax throughout
src/gradata/events_bus.py	In-memory EventBus correctly isolates handler errors, bounds listeners to 50, and uses a thread pool — well-implemented
src/gradata/hooks/auto_correct.py	PostToolUse hook; well-structured with proper error handling at every call site
src/gradata/_core.py	Brain core logic; robust try/except wrapping throughout the correction and graduation pipeline
src/gradata/rules/rule_tracker.py	Rule application tracker; three print() warning calls should be replaced with logging.warning()
src/gradata/mcp_server.py	MCP JSON-RPC server; two print() calls in brain-init path should use logging.info() / logging.error()
src/gradata/_embed.py	Embedding client; print() for missing API key error and missing from future import annotations

Sequence Diagram

sequenceDiagram
    participant U as User/Agent
    participant B as Brain
    participant EB as EventBus (in-memory)
    participant EV as _events (JSONL+SQLite)

    U->>B: brain.correct(draft, final)
    B->>EV: emit("CORRECTION", ...) — dual-write
    EV-->>B: event dict (with id)
    B->>EB: bus.emit("correction.created", payload)
    EB-->>EB: _safe_call(handler, payload) — errors isolated

    U->>B: brain.end_session()
    B->>EV: emit("SESSION_END", ...)
    B->>EB: bus.emit("session.ended", stats)
    EB-->>EB: _safe_call per subscriber

Loading

Comments Outside Diff (3)

1. src/gradata/_events.py, line 107-122 (link)

   print() used for error logging

   Both JSONL and SQLite write-failure handlers use print(..., file=sys.stderr) instead of the logging module. These messages are invisible to any caller that routes log output through a handler, and cannot be filtered by severity level. The same pattern appears in several other SDK modules:

   • src/gradata/rules/rule_tracker.py:63, :87, :122 — warning-level messages
   • src/gradata/mcp_server.py:505, :511 — brain-init status messages
   • src/gradata/_embed.py:149 — missing API key error

   All of these should use logging.warning() or logging.error() so callers can control log visibility. For example, in _events.py lines 107 and 122:

           except Exception as e:
               logging.getLogger("gradata.events").error("[events] JSONL write failed: %s", e)

           except Exception as e:
               logging.getLogger("gradata.events").error("[events] SQLite write failed: %s", e)

   Rule Used: # Code Review Rules

   Rule 1: Never use print() ... (source)

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/gradata/_events.py
   Line: 107-122
   
   Comment:
   **`print()` used for error logging**
   
   Both JSONL and SQLite write-failure handlers use `print(..., file=sys.stderr)` instead of the `logging` module. These messages are invisible to any caller that routes log output through a handler, and cannot be filtered by severity level. The same pattern appears in several other SDK modules:
   
   - `src/gradata/rules/rule_tracker.py:63`, `:87`, `:122` — warning-level messages
   - `src/gradata/mcp_server.py:505`, `:511` — brain-init status messages
   - `src/gradata/_embed.py:149` — missing API key error
   
   All of these should use `logging.warning()` or `logging.error()` so callers can control log visibility. For example, in `_events.py` lines 107 and 122:
   
   ```python
           except Exception as e:
               logging.getLogger("gradata.events").error("[events] JSONL write failed: %s", e)
   ```
   
   ```python
           except Exception as e:
               logging.getLogger("gradata.events").error("[events] SQLite write failed: %s", e)
   ```
   
   **Rule Used:** # Code Review Rules
   
   ## Rule 1: Never use print() ... ([source](https://app.greptile.com/review/custom-context?memory=dee613fe-ca52-4382-b9d7-fad6d0b079ec))
   
   How can I resolve this? If you propose a fix, please make it concise.

   

2. src/gradata/_paths.py, line 1-12 (link)

   Missing from __future__ import annotations

   _paths.py is a core SDK module that uses str | Path | None union syntax in several public function signatures (e.g. resolve_brain_dir, BrainContext.from_brain_dir, set_brain_dir), but it is missing from __future__ import annotations. Rule 6 requires this import in every Python SDK file.

   The same import is missing from:

   • src/gradata/_doctor.py
   • src/gradata/_embed.py
   • src/gradata/cli.py
   • src/gradata/_installer.py
   • src/gradata/_validator.py

   Add from __future__ import annotations as the first import (after the module docstring) in each of these files.

   Rule Used: # Code Review Rules

   Rule 1: Never use print() ... (source)

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/gradata/_paths.py
   Line: 1-12
   
   Comment:
   **Missing `from __future__ import annotations`**
   
   `_paths.py` is a core SDK module that uses `str | Path | None` union syntax in several public function signatures (e.g. `resolve_brain_dir`, `BrainContext.from_brain_dir`, `set_brain_dir`), but it is missing `from __future__ import annotations`. Rule 6 requires this import in every Python SDK file.
   
   The same import is missing from:
   - `src/gradata/_doctor.py`
   - `src/gradata/_embed.py`
   - `src/gradata/cli.py`
   - `src/gradata/_installer.py`
   - `src/gradata/_validator.py`
   
   Add `from __future__ import annotations` as the first import (after the module docstring) in each of these files.
   
   **Rule Used:** # Code Review Rules
   
   ## Rule 1: Never use print() ... ([source](https://app.greptile.com/review/custom-context?memory=dee613fe-ca52-4382-b9d7-fad6d0b079ec))
   
   How can I resolve this? If you propose a fix, please make it concise.

   

3. src/gradata/_events.py, line 198-216 (link)

   supersede() ignores BrainContext, silently routes to the wrong database in multi-brain setups

   emit() and query() both accept an optional ctx: BrainContext | None parameter so they can be directed at a specific brain's database. However supersede() hard-codes _p.DB_PATH (the process-global path) at line 201 and passes no ctx to its internal emit() call at lines 210–213. In a process with two Brain instances, calling supersede() on events belonging to the second brain will silently read from and write to the first brain's database.

   The same issue affects:

   • correction_rate() (line 220) — uses _p.DB_PATH directly
   • compute_leading_indicators() (line 231) — uses _p.DB_PATH directly
   • audit_trend() (line 376) — uses _p.DB_PATH directly

   Each of these functions should accept ctx: BrainContext | None = None and resolve db_path = ctx.db_path if ctx else _p.DB_PATH, consistent with emit() and query().

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: src/gradata/_events.py
   Line: 198-216
   
   Comment:
   **`supersede()` ignores `BrainContext`, silently routes to the wrong database in multi-brain setups**
   
   `emit()` and `query()` both accept an optional `ctx: BrainContext | None` parameter so they can be directed at a specific brain's database. However `supersede()` hard-codes `_p.DB_PATH` (the process-global path) at line 201 and passes no `ctx` to its internal `emit()` call at lines 210–213. In a process with two `Brain` instances, calling `supersede()` on events belonging to the second brain will silently read from and write to the first brain's database.
   
   The same issue affects:
   - `correction_rate()` (line 220) — uses `_p.DB_PATH` directly
   - `compute_leading_indicators()` (line 231) — uses `_p.DB_PATH` directly
   - `audit_trend()` (line 376) — uses `_p.DB_PATH` directly
   
   Each of these functions should accept `ctx: BrainContext | None = None` and resolve `db_path = ctx.db_path if ctx else _p.DB_PATH`, consistent with `emit()` and `query()`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/gradata/_events.py
Line: 107-122

Comment:
**`print()` used for error logging**

Both JSONL and SQLite write-failure handlers use `print(..., file=sys.stderr)` instead of the `logging` module. These messages are invisible to any caller that routes log output through a handler, and cannot be filtered by severity level. The same pattern appears in several other SDK modules:

- `src/gradata/rules/rule_tracker.py:63`, `:87`, `:122` — warning-level messages
- `src/gradata/mcp_server.py:505`, `:511` — brain-init status messages
- `src/gradata/_embed.py:149` — missing API key error

All of these should use `logging.warning()` or `logging.error()` so callers can control log visibility. For example, in `_events.py` lines 107 and 122:

```python
        except Exception as e:
            logging.getLogger("gradata.events").error("[events] JSONL write failed: %s", e)
```

```python
        except Exception as e:
            logging.getLogger("gradata.events").error("[events] SQLite write failed: %s", e)
```

**Rule Used:** # Code Review Rules

## Rule 1: Never use print() ... ([source](https://app.greptile.com/review/custom-context?memory=dee613fe-ca52-4382-b9d7-fad6d0b079ec))

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/gradata/_paths.py
Line: 1-12

Comment:
**Missing `from __future__ import annotations`**

`_paths.py` is a core SDK module that uses `str | Path | None` union syntax in several public function signatures (e.g. `resolve_brain_dir`, `BrainContext.from_brain_dir`, `set_brain_dir`), but it is missing `from __future__ import annotations`. Rule 6 requires this import in every Python SDK file.

The same import is missing from:
- `src/gradata/_doctor.py`
- `src/gradata/_embed.py`
- `src/gradata/cli.py`
- `src/gradata/_installer.py`
- `src/gradata/_validator.py`

Add `from __future__ import annotations` as the first import (after the module docstring) in each of these files.

**Rule Used:** # Code Review Rules

## Rule 1: Never use print() ... ([source](https://app.greptile.com/review/custom-context?memory=dee613fe-ca52-4382-b9d7-fad6d0b079ec))

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/gradata/_events.py
Line: 198-216

Comment:
**`supersede()` ignores `BrainContext`, silently routes to the wrong database in multi-brain setups**

`emit()` and `query()` both accept an optional `ctx: BrainContext | None` parameter so they can be directed at a specific brain's database. However `supersede()` hard-codes `_p.DB_PATH` (the process-global path) at line 201 and passes no `ctx` to its internal `emit()` call at lines 210–213. In a process with two `Brain` instances, calling `supersede()` on events belonging to the second brain will silently read from and write to the first brain's database.

The same issue affects:
- `correction_rate()` (line 220) — uses `_p.DB_PATH` directly
- `compute_leading_indicators()` (line 231) — uses `_p.DB_PATH` directly
- `audit_trend()` (line 376) — uses `_p.DB_PATH` directly

Each of these functions should accept `ctx: BrainContext | None = None` and resolve `db_path = ctx.db_path if ctx else _p.DB_PATH`, consistent with `emit()` and `query()`.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "test: trigger Greptile review" | Re-trigger Greptile}

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}

Context used:

• Rule used - # Code Review Rules

Rule 1: Never use print() ... (source)