Context
The QueryFacade (ADR-048) has an execute_raw() escape hatch that logs a warning on every call. This is working as designed — it flags raw Cypher that bypasses the safe query layer. However, several callers are established patterns that run on every ingest cycle, generating noisy warnings during normal operation.
Current State
| Caller |
Raw Calls |
Namespace |
Frequency |
source_embedding_worker.py |
10 |
embedding_status |
Every chunk during ingest |
polarity_axis.py |
1 |
(default) |
On polarity analysis |
vocab_consolidation.py |
1 |
vocabulary |
On vocab consolidation |
database.py |
1 |
(admin) |
Admin query endpoint |
The source embedding worker dominates — 10 raw queries per chunk means a batch ingest of 7 documents generates hundreds of escape hatch warnings.
Proposed Improvement
Promote the recurring execute_raw patterns into typed QueryFacade methods:
facade.get_sources_needing_embedding()
facade.update_source_embedding()
facade.get_embedding_status()
facade.get_vocab_consolidation_candidates()
facade.project_polarity_axis()
- Other patterns as discovered during implementation
Each new method would go through the facade's safe query path (parameterized, audited, logged as safe rather than raw).
What NOT to change
- Keep the
execute_raw() escape hatch and its warning at WARNING level — it's valuable for catching new raw query usage that should be promoted
- Keep the admin query endpoint (
database.py) as raw — it's intentionally a raw query interface
- Don't remove
execute_raw() itself — it remains the valid path for one-off or complex queries that don't justify a dedicated method
Acceptance Criteria
Context
The QueryFacade (ADR-048) has an
execute_raw()escape hatch that logs a warning on every call. This is working as designed — it flags raw Cypher that bypasses the safe query layer. However, several callers are established patterns that run on every ingest cycle, generating noisy warnings during normal operation.Current State
source_embedding_worker.pyembedding_statuspolarity_axis.pyvocab_consolidation.pyvocabularydatabase.pyThe source embedding worker dominates — 10 raw queries per chunk means a batch ingest of 7 documents generates hundreds of escape hatch warnings.
Proposed Improvement
Promote the recurring
execute_rawpatterns into typed QueryFacade methods:facade.get_sources_needing_embedding()facade.update_source_embedding()facade.get_embedding_status()facade.get_vocab_consolidation_candidates()facade.project_polarity_axis()Each new method would go through the facade's safe query path (parameterized, audited, logged as safe rather than raw).
What NOT to change
execute_raw()escape hatch and its warning atWARNINGlevel — it's valuable for catching new raw query usage that should be promoteddatabase.py) as raw — it's intentionally a raw query interfaceexecute_raw()itself — it remains the valid path for one-off or complex queries that don't justify a dedicated methodAcceptance Criteria
execute_raw()warning remains for genuinely raw/unknown queries