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-serviceto 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-corefor 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
detectUnsafeInputwith default unsafe terms - Mode selector
selectMeditationModeand defaults for quick/standard/deep sessions
- Safety helper
- Updated
meditation-generationandspiritual-guidanceto consume shared safety helper. - Add further adoptions in
meditation-experienceandspiritual-embeddingsas needed.
Testing Strategy#
- Unit tests in
meditation-corecover 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-coreand bump dependents.
Communication#
- Share with meditation/guidance service owners; link this ADR in contributor docs.