Eve library

ADR-0005: Meditation/GUIDANCE Service Consolidation Strategy

ADR

Revision 1

On this page

Date: 2025-12-04
Status: Rejected (single monolith); Accepted (shared @lilith/meditation-core)
Authors: @codex-agent
Reviewers: —
Deciders: Platform Architecture WG

Context#

  • Four related services handle meditation/guidance flows: meditation-generation, meditation-experience, spiritual-embeddings, spiritual-guidance.
  • A TODO requested merging them into one unified @lilith/meditation-service to remove duplication.
  • Each service has distinct responsibilities and dependencies (LLM/tts pipelines, embeddings generation, persona guidance, experience packaging), different SLA/latency targets, and different API shapes.

Decision#

  • Do not merge the meditation/guidance services into a single service. Keep domain-focused deployments.
  • Adopt a shared helper package @lilith/meditation-core for common safety checks (unsafe prompt detection) and mode-selection logic so behavior stays consistent without coupling runtimes.

Rationale#

  • A monolithic service would mix divergent concerns (LLM script gen, embeddings, guidance personas, experience delivery), increasing blast radius and slowing iteration.
  • Shared helpers capture the genuine overlap (safety guardrails, mode selection defaults) with minimal risk and no API changes.
  • This mirrors the token consolidation approach: shared primitives over forced service fusion.

Alternatives Considered#

Option 1: Single unified @lilith/meditation-service#

  • Pros: One deployment, fewer repos.
  • Cons: Complex routing/flags, mixed SLAs, larger failure surface, harder scaling paths.
  • Decision: Rejected.

Option 2: Leave services entirely independent#

  • Pros: No work.
  • Cons: Divergent safety rules and UX modes, duplicated logic.
  • Decision: Rejected.

Option 3: Shared core helpers (Chosen)#

  • Pros: Consistent safety/mode logic, low-risk adoption, preserves service boundaries.
  • Cons: Requires light refactors to consume helpers.

Implementation#

  • Added services/meditation-core/ exporting:
    • Safety helper detectUnsafeInput with default unsafe terms
    • Mode selector selectMeditationMode and defaults for quick/standard/deep sessions
  • Updated meditation-generation and spiritual-guidance to consume shared safety helper.
  • Add further adoptions in meditation-experience and spiritual-embeddings as needed.

Testing Strategy#

  • Unit tests in meditation-core cover safety detection and mode selection.
  • Service-level behavior remains unchanged aside from centralized safety checks; integration tests should continue to pass.

Impact#

  • Services affected: meditation-generation, spiritual-guidance (now reuse core safety); others can adopt over time.
  • Performance: Neutral.
  • Security/Safety: More consistent unsafe-content blocking.

Metrics / Success Criteria#

  • Shared safety/mode helpers used across all meditation/guidance services.
  • No regressions in existing API contracts.
  • Reduced duplication of unsafe-term lists and mode logic.

Timeline#

  • Decision date: 2025-12-04
  • Further adoptions: incremental as services are touched.

Risks & Mitigation#

  • Partial adoption could leave drift; track remaining services to migrate.
  • If future modes/safety lists evolve, update meditation-core and bump dependents.

Communication#

  • Share with meditation/guidance service owners; link this ADR in contributor docs.