# ADR-0005: Meditation/GUIDANCE Service Consolidation Strategy

**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.
