# Code Review Summary

Date: 2026-03-28

Scope: combined review covering both the full repository state and an earlier pass over recent/local changes.

## Project-Wide Findings

### 1. High: Flight can start successfully while the REST API still reports it as disabled

- Files:
  - [src/orionbelt/api/app.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/app.py#L71)
  - [src/orionbelt/api/app.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/app.py#L103)
  - [src/orionbelt/api/routers/settings.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/settings.py#L20)

`flight_info` and `query_execute_enabled` are computed before Flight auto-detection runs. Later in startup, the app may still detect `ob_flight`, start the Flight server, and set `settings.flight_enabled = True`, but the cached dependency state is not refreshed. That leaves `/v1/settings` and the query execution gating out of sync with the actual runtime state.

Impact:
- The server can expose Flight successfully while reporting `flight: null`.
- `query_execute` can remain `false` even though Flight startup is supposed to enable it.
- Clients relying on `/v1/settings` can misconfigure themselves or hide working features.

Verification:
- I reproduced this by patching in a minimal `ob_flight` module. The app started Flight once, but `/v1/settings` still returned `{"query_execute": false, "flight": null}`.

### 2. High: Top-level shortcut endpoints break in single-model mode after creating a second session

- Files:
  - [src/orionbelt/api/routers/sessions.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/sessions.py#L72)
  - [src/orionbelt/api/routers/shortcuts.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/shortcuts.py#L62)
  - [src/orionbelt/api/routers/shortcuts.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/shortcuts.py#L101)
  - [tests/integration/test_api.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/tests/integration/test_api.py#L433)

Single-model mode preloads the same model into every new session. The shortcut resolution code then counts each per-session copy as a separate candidate and returns `409` whenever more than one exists. That contradicts the documented shortcut behavior for single-model mode.

Impact:
- `/v1/schema`, `/v1/query/sql`, `/v1/query/execute`, and similar top-level endpoints stop working as soon as a second session is created.
- The failure is easy to trigger in normal multi-client usage.

Verification:
- I reproduced `/v1/schema` returning `404`, then `200` after creating one session, then `409` after creating a second session in single-model mode.

### 3. Medium: The advertised default test flow is broken in a clean checkout

- Files:
  - [pyproject.toml](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/pyproject.toml#L61)
  - [tests/unit/test_db_executor.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/tests/unit/test_db_executor.py#L64)
  - [src/orionbelt/service/db_executor.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/service/db_executor.py#L165)

The root package keeps Flight/driver support behind the optional `flight` extra, but the default unit suite assumes `ob_driver_core` and `ob_flight` are importable. As a result, the documented `uv run pytest` path does not hold for a standard install without extra packages.

Impact:
- Fresh contributors get failing tests from project configuration, not from their changes.
- CI/setup becomes brittle unless every job installs the optional Flight stack.
- The failing tests obscure real regressions.

Verification:
- `uv run pytest tests/unit -q` produced `640 passed, 9 failed`.
- All 9 failures were `ModuleNotFoundError` for `ob_driver_core` or `ob_flight`, originating from [tests/unit/test_db_executor.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/tests/unit/test_db_executor.py#L64).
- `uv run --extra dev mypy src/orionbelt` also reported unresolved `ob_flight.*` imports in the main package.

### 4. Medium: The public `/v1/validate` shortcut is not actually stateless

- Files:
  - [src/orionbelt/api/routers/shortcuts.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/shortcuts.py#L288)
  - [src/orionbelt/api/routers/shortcuts.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/api/routers/shortcuts.py#L302)

The top-level validation endpoint resolves an existing store first and returns `404 No active sessions` when none exists. Validation itself only needs the posted YAML, so tying it to session existence is unnecessary and makes the endpoint fail in the simplest usage.

Impact:
- `POST /v1/validate` fails on a fresh server with no sessions.
- This is surprising for API consumers and inconsistent with the endpoint’s shape.

Verification:
- I reproduced `POST /v1/validate` returning `404 {"detail": "No active sessions"}` on a newly initialized app.

## Focused Review Of Recent And Local Changes

Reviewed the current repo state on `main` with emphasis on:

- Local worktree changes: `uv.lock` and untracked `scripts` symlink
- Recent post-merge changes in `c8aed2c..HEAD`
- Affected files:
  - [src/orionbelt/ui/app.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/ui/app.py)
  - [src/orionbelt/compiler/filters.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/compiler/filters.py)
  - [src/orionbelt/compiler/graph.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/compiler/graph.py)
  - [src/orionbelt/compiler/pop_wrap.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/compiler/pop_wrap.py)
  - [src/orionbelt/compiler/resolution.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/compiler/resolution.py)
  - [src/orionbelt/compiler/star.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/compiler/star.py)
  - [src/orionbelt/parser/resolver.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/parser/resolver.py)
  - [docs/index.md](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/docs/index.md)

Findings for that narrower diff-based review:

- No actionable correctness or regression findings in the reviewed recent code changes.
- The recent commits were effectively formatting-only compiler/parser edits, a local variable rename in [src/orionbelt/ui/app.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/ui/app.py), and a docs-only homepage edit.
- None of those diffs appeared to introduce a new runtime defect.

Notes:

- The local worktree change in [uv.lock](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/uv.lock) is a package version sync from `1.2.0` to `1.2.1`, matching `pyproject.toml`, `src/orionbelt/__init__.py`, `README.md`, and `CHANGELOG.md`.
- The untracked `scripts` entry is a symlink to `../orionbelt-infra`, not a new in-repo scripts directory.
- `uv run --extra dev mypy src/orionbelt/ui/app.py` still reports one pre-existing type-check issue around untyped `gradio`, not caused by the reviewed rename.

## Verification

Commands run:

```bash
uv run pytest tests/unit -q
uv run ruff check src tests drivers
uv run --extra dev mypy src/orionbelt
PYTHONPATH=src pytest -q tests/unit/test_pop.py tests/unit/test_parser.py tests/unit/test_measure_filters.py tests/unit/test_graph.py
uv run --extra dev mypy src/orionbelt/ui/app.py
```

Results:

- `uv run pytest tests/unit -q`: `640 passed, 9 failed`
- `uv run ruff check src tests drivers`: `143 errors`, mostly driver-package lint/type-annotation issues
- `uv run --extra dev mypy src/orionbelt`: 6 errors, including unresolved `ob_flight.*` imports in the main package
- `PYTHONPATH=src pytest -q tests/unit/test_pop.py tests/unit/test_parser.py tests/unit/test_measure_filters.py tests/unit/test_graph.py`: `107 passed in 0.71s`
- `uv run --extra dev mypy src/orionbelt/ui/app.py`: failed on untyped `gradio` import, not on the renamed variable

## Residual Risk

- I did not run the full integration suite or Docker-based tests.
- The review focused on correctness, runtime behavior, packaging consistency, and API behavior rather than style-only issues.
- There is still limited automated coverage around the touched UI helper path in [src/orionbelt/ui/app.py](/Users/ralfbecher/Documents/GitHub/orionbelt-semantic-layer/src/orionbelt/ui/app.py), so that narrower rename review remains inspection-heavy.
