# Layer 1: Cross-Reference Validation Report
**Date**: 2026-02-15  
**Protocol**: Pre-Dev Gate - Layer 1  
**Scope**: Structural consistency, feature traceability, ADR alignment, configuration consistency

---

## Phase 1.1: Structural Consistency

### Path Consistency Table

| Documented Path | Actual Path | Status | Notes |
|----------------|-------------|--------|-------|
| `llmhosts/db/` | ❌ Not found | **ERROR** | Docs specify `llmhosts/db/engine.py`, `llmhosts/db/models.py`, `llmhosts/db/migrations/`. Code uses direct SQLite connections in `llmhosts/metrics/`, `llmhosts/audit/`, `llmhosts/embeddings/`. No centralized DB layer. |
| `llmhosts/paths.py` | ❌ Not found | **WARNING** | Implementation blueprint Step 2 specifies `llmhosts/paths.py` for XDG-compliant paths. Path resolution is in `llmhosts/config.py` instead. |
| `llmhosts/backend/` | ✅ `llmhosts/backends/` | **WARNING** | Docs use singular `backend/`, code uses plural `backends/`. Functionality exists but path differs. |
| `llmhosts/router/engine.py` | ✅ Exists | **PASS** | Tier 0 rule engine exists. |
| `llmhosts/router/knn.py` | ✅ Exists | **PASS** | Tier 1 kNN router exists. |
| `llmhosts/router/modernbert.py` | ✅ Exists | **PASS** | Tier 2 ModernBERT classifier exists. |
| `llmhosts/router/` (Tier 3 Qwen) | ⚠️ Not found | **WARNING** | ADR-001 specifies Tier 3 Qwen-0.5B reasoning router. No `qwen.py` or similar found. May be Phase 2. |
| `llmhosts/cache/exact.py` | ✅ Exists | **PASS** | Tier 0 exact hash cache exists. |
| `llmhosts/cache/namespace.py` | ✅ Exists | **PASS** | Tier 1 entity namespace cache exists. |
| `llmhosts/cache/vcache.py` | ✅ Exists | **PASS** | Tier 2 vCache semantic cache exists. |
| `llmhosts/discovery/ollama.py` | ✅ Exists | **PASS** | Ollama discovery exists. |
| `llmhosts/discovery/hardware.py` | ✅ Exists | **PASS** | Hardware detection exists. |
| `llmhosts/discovery/tunnel.py` | ✅ Exists | **PASS** | Tunnel detection exists. |
| `llmhosts/keys/` | ✅ Exists | **PASS** | BYOK key management exists. |
| `llmhosts/metrics/` | ✅ Exists | **PASS** | Cost tracking exists. |
| `llmhosts/dashboard/` | ✅ Exists | **PASS** | Dashboard module exists. |
| `llmhosts/proxy/` | ✅ Exists | **PASS** | FastAPI proxy exists. |
| `llmhosts/tunnel/` | ✅ Exists | **PASS** | Tunnel module exists (Phase 2 feature implemented early). |
| `llmhosts/cli.py` | ✅ Exists | **PASS** | CLI entrypoint exists. |
| `llmhosts/config.py` | ✅ Exists | **PASS** | Config loading exists. |
| `llmhosts/constants.py` | ✅ Exists | **PASS** | Constants file exists. |
| `llmhosts/server.py` | ✅ Exists | **PASS** | Server orchestration exists. |
| `llmhosts/doctor.py` | ✅ Exists | **PASS** | Doctor command exists. |
| `.docker/entrypoint.sh` | ✅ Exists | **PASS** | Docker entrypoint exists. |

**Summary**: 1 ERROR, 3 WARNINGS, 20 PASS

---

## Phase 1.2: Feature Traceability

### Phase 1 Features (F-001 through F-012)

| Feature ID | Feature Name | Code Files | Status | Notes |
|-----------|--------------|------------|--------|-------|
| F-001 | OpenAI API Proxy | `llmhosts/proxy/routes_openai.py`, `llmhosts/proxy/app.py` | ✅ **PASS** | `/v1/chat/completions` endpoint exists. |
| F-002 | Anthropic API Proxy | `llmhosts/proxy/routes_anthropic.py` | ✅ **PASS** | `/v1/messages` endpoint exists. |
| F-003 | Ollama Auto-Discovery | `llmhosts/discovery/ollama.py`, `llmhosts/proxy/dispatcher.py` | ✅ **PASS** | Auto-discovery at `localhost:11434` implemented. |
| F-004 | BYOK Cloud Keys | `llmhosts/keys/manager.py`, `llmhosts/keys/crypto.py` | ✅ **PASS** | Key management with encryption exists. |
| F-005 | Rule-Based Router | `llmhosts/router/engine.py` | ✅ **PASS** | Tier 0 rule engine implemented. |
| F-006 | Cost Tracking | `llmhosts/metrics/collector.py`, `llmhosts/router/cost.py` | ✅ **PASS** | Cost tracking implemented. |
| F-007 | Exact Hash Cache | `llmhosts/cache/exact.py` | ✅ **PASS** | SHA-256 exact match cache exists. |
| F-008 | TUI Dashboard | `llmhosts/dashboard/tui.py` | ✅ **PASS** | TUI dashboard exists. |
| F-009 | Web Dashboard | `llmhosts/dashboard/web/` | ⚠️ **PARTIAL** | Dashboard module exists, need to verify React SPA implementation. |
| F-010 | `llmhosts serve` | `llmhosts/cli.py:serve()`, `llmhosts/server.py` | ✅ **PASS** | Serve command implemented. |
| F-011 | `llmhosts doctor` | `llmhosts/cli.py:doctor()`, `llmhosts/doctor.py` | ✅ **PASS** | Doctor command implemented. |
| F-012 | Hardware Detection | `llmhosts/discovery/hardware.py` | ✅ **PASS** | GPU/CPU/RAM detection exists. |

### Phase 2 Features (F-013 through F-020) - Early Implementation Check

| Feature ID | Feature Name | Code Files | Status | Notes |
|-----------|--------------|------------|--------|-------|
| F-013 | `llmhosts tunnel` | `llmhosts/cli.py:tunnel()`, `llmhosts/tunnel/` | ✅ **IMPLEMENTED** | Phase 2 feature implemented early. |
| F-014 | kNN Router (Tier 1) | `llmhosts/router/knn.py` | ✅ **IMPLEMENTED** | Phase 2 feature implemented early. |
| F-015 | Entity Namespace Cache | `llmhosts/cache/namespace.py` | ✅ **IMPLEMENTED** | Phase 2 feature implemented early. |
| F-016 | vCache Semantic (Tier 2) | `llmhosts/cache/vcache.py` | ✅ **IMPLEMENTED** | Phase 2 feature implemented early. |
| F-017 | Cloud Cost Dashboard | ❌ Not found | **NOT STARTED** | Phase 2 feature not implemented. |
| F-018 | Multi-Device Mesh | ❌ Not found | **NOT STARTED** | Phase 2 feature not implemented. |
| F-019 | Honest Savings Display | ⚠️ Partial | **PARTIAL** | Cost tracking exists, need to verify baseline capture and comparison. |
| F-020 | ModernBERT Router (Tier 2) | `llmhosts/router/modernbert.py` | ✅ **IMPLEMENTED** | Phase 2 feature implemented early. |

**Summary**: Phase 1: 11 PASS, 1 PARTIAL. Phase 2: 5 IMPLEMENTED EARLY, 2 NOT STARTED, 1 PARTIAL.

---

## Phase 1.3: ADR Alignment

### ADR Compliance Table

| ADR | Decision | Code Evidence | Status | Notes |
|-----|----------|---------------|--------|-------|
| ADR-001 | Three-tier hybrid router | `llmhosts/router/engine.py` (Tier 0), `llmhosts/router/knn.py` (Tier 1), `llmhosts/router/modernbert.py` (Tier 2) | ⚠️ **PARTIAL** | Tier 0, 1, 2 exist. Tier 3 (Qwen-0.5B) not found. ADR says Phase 2 for Tier 3, so this may be expected. |
| ADR-002 | Ollama-primary, vLLM opt-in | `llmhosts/discovery/ollama.py`, `llmhosts/proxy/dispatcher.py` | ✅ **PASS** | Ollama discovery and routing implemented. vLLM opt-in path exists but not fully implemented. |
| ADR-003 | LiteLLM as API proxy | `llmhosts/backends/litellm_backend.py`, `llmhosts/backends/manager.py` | ✅ **PASS** | LiteLLM backend wrapper exists. Code uses LiteLLM for cloud API routing via BYOK keys. |
| ADR-004 | Phase 1: localhost only | `llmhosts/tunnel/` exists | ⚠️ **WARNING** | ADR-004 says Phase 1 is localhost-only, but `llmhosts/tunnel/` is implemented (Phase 2 feature). This is early implementation, not a violation, but worth noting. |
| ADR-005 | Next.js + TailwindCSS + shadcn/ui | `llmhosts/dashboard/web/` | ⚠️ **UNKNOWN** | Dashboard module exists but need to verify Next.js implementation. May be bundled React SPA instead. |
| ADR-006 | Model Context Protocol (MCP) | ❌ Not found | **NOT IMPLEMENTED** | ADR-006 specifies MCP for tool integration. No MCP implementation found. May be Phase 2+. |
| ADR-007 | Docker Compose + K3s | `docker-compose.yml`, `Dockerfile`, `Dockerfile.dev` | ✅ **PASS** | Docker Compose exists. K3s configs not found but may be Phase 3+. |
| ADR-008 | Tiered pip install | `pyproject.toml` with `[smart]` and `[full]` extras | ✅ **PASS** | Package is tiered: core, smart, full. Matches ADR-008. |

**Summary**: 4 PASS, 2 PARTIAL/WARNING, 1 UNKNOWN, 1 NOT IMPLEMENTED

---

## Phase 1.4: Configuration Consistency

### Configuration Consistency Table

| Configuration Item | Documented Value | Actual Value | Status | Notes |
|-------------------|------------------|--------------|--------|-------|
| OLLAMA_DEFAULT_HOST | `localhost:11434` | `http://127.0.0.1:11434` (from `constants.py`) | ✅ **PASS** | Matches (with protocol prefix). |
| OLLAMA_DEFAULT_PORT | `11434` | `11434` (from `constants.py`) | ✅ **PASS** | Matches. |
| Proxy Port | `4000` | `4000` (from `constants.py`) | ✅ **PASS** | Matches. |
| Proxy Host | `0.0.0.0` (config default) | `127.0.0.1` (constants default) | ⚠️ **WARNING** | Config schema says `0.0.0.0`, constants say `127.0.0.1`. Need to verify which is used. |
| Entry Point (`pyproject.toml`) | `llmhost.cli:main` | `llmhost.cli:main` | ✅ **PASS** | Matches. |
| Docker Entrypoint | `llmhosts serve` | `ENTRYPOINT ["llmhost"]` + `CMD ["serve"]` | ✅ **PASS** | Matches. |
| Config File Path | `~/.llmhosts/config.toml` | `~/.llmhosts/config.toml` (from `config.py`) | ✅ **PASS** | Matches. |
| Database Path | `~/.llmhosts/data/llmhosts.db` | Various (metrics, audit, embeddings use separate DBs) | ⚠️ **WARNING** | Docs specify single `llmhost.db`. Code uses multiple SQLite files. |
| FAISS Index Path | `~/.llmhosts/data/router.faiss` | `router.faiss` (from `constants.py`) | ⚠️ **PARTIAL** | Filename matches, need to verify full path resolution. |

**Summary**: 5 PASS, 3 WARNINGS

---

## Critical Findings Summary

### ERRORS (Must Fix)
1. **Missing Database Layer (`llmhosts/db/`)**: Documentation specifies a centralized database layer with Alembic migrations (`llmhosts/db/engine.py`, `llmhosts/db/models.py`, `llmhosts/db/migrations/`), but code uses direct SQLite connections scattered across modules (`llmhosts/metrics/`, `llmhosts/audit/`, `llmhosts/embeddings/`). This violates the implementation blueprint Step 3 and system architecture data model.

### WARNINGS (Should Address)
1. **Path Naming Inconsistency**: Docs use `llmhosts/backend/` (singular), code uses `llmhosts/backends/` (plural).
2. **Missing `paths.py`**: Implementation blueprint Step 2 specifies `llmhosts/paths.py` for XDG-compliant paths, but path resolution is in `config.py` instead.
3. **Tier 3 Router Missing**: ADR-001 specifies Tier 3 (Qwen-0.5B reasoning router), but no implementation found. May be Phase 2 as intended.
4. **Phase 1 Tunnel Implementation**: ADR-004 says Phase 1 is localhost-only, but `llmhosts/tunnel/` is implemented (Phase 2 feature). Early implementation is acceptable but worth noting.
5. **Proxy Host Default Mismatch**: Config schema default is `0.0.0.0`, constants default is `127.0.0.1`. Need to align.
6. **Database Path Fragmentation**: Docs specify single `llmhost.db`, but code uses multiple SQLite files (metrics, audit, embeddings). May be intentional but needs documentation alignment.

### POSITIVE FINDINGS
1. **Router Tiers**: All three tiers (0, 1, 2) are implemented as specified in ADR-001.
2. **Cache Tiers**: All three cache tiers (exact, namespace, semantic) are implemented.
3. **LiteLLM Integration**: ADR-003 compliance verified - LiteLLM backend wrapper exists and is used.
4. **Tiered Package**: ADR-008 compliance verified - `pyproject.toml` has `[smart]` and `[full]` extras.
5. **Early Phase 2 Features**: Several Phase 2 features (tunnel, kNN, namespace cache, vCache, ModernBERT) are already implemented, showing good progress.

---

## Recommendations

1. **CRITICAL**: Implement centralized database layer (`llmhosts/db/`) with Alembic migrations as specified in implementation blueprint Step 3. Migrate existing SQLite usage to use the centralized engine.
2. **HIGH**: Align proxy host default between config schema and constants.
3. **MEDIUM**: Create `llmhosts/paths.py` for XDG-compliant path resolution, or update implementation blueprint to reflect that paths are in `config.py`.
4. **MEDIUM**: Update documentation to reflect that `llmhosts/backends/` (plural) is the actual path, or rename code to match docs.
5. **LOW**: Document database path fragmentation decision (multiple SQLite files vs single DB) or consolidate to single DB.
6. **LOW**: Verify web dashboard implementation matches ADR-005 (Next.js vs bundled React SPA).

---

## Overall Assessment

**Status**: ⚠️ **CONDITIONAL PASS WITH REMEDIATION REQUIRED**

The codebase shows strong alignment with architecture documents in most areas, with excellent progress on Phase 1 features and even early implementation of Phase 2 features. However, the missing centralized database layer is a critical architectural gap that must be addressed before proceeding to Layer 2 validation.

**Next Steps**:
1. Fix ERROR-level findings (database layer)
2. Address HIGH-priority warnings (proxy host, paths.py)
3. Re-run Layer 1 validation after fixes
4. Proceed to Layer 2 (API Contract Validation) once Layer 1 passes
