Skip to content

feat: promote execute_raw patterns to safe QueryFacade methods #355

@aaronsb

Description

@aaronsb

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

  • Source embedding worker calls promoted to facade methods
  • Polarity axis calls promoted to facade methods
  • Vocab consolidation calls promoted to facade methods
  • Existing tests pass
  • Ingest cycle produces no escape hatch warnings for standard operations
  • execute_raw() warning remains for genuinely raw/unknown queries

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions