# @oshun/domain-tara

Typed Tara domain adapter package for the OSHUN shell.

## Included

- Tara adapter contracts (`TaraApiAdapter`)
- Canonical shell-facing Tara adapter contract (`TaraDomainAdapter`)
- Canonical Tara object models for rituals, reusable meditations, and
  meditation-session records
- Canonical Tara ritual-template, ritual-step, ritual-trigger, and ritual
  completion contracts
- Canonical Tara ritual-assembly rules for composing meditation, breathwork,
  passage, journaling, and Nyx perspective steps
- Canonical Tara ritual scheduling and reminder orchestration
- Canonical Tara ritual edit, skip, recover, and reschedule operations
- Canonical Tara ritual completion events and downstream projection helpers for
  home, activity, search, and recommendations
- Tara recommendation/continue/health response models
- Adapter factory (`createTaraDomainAdapter`) with typed error handling
- Home/Explore Tara card model builders for OSHUN shell surfaces
- Tara launch-action mapping helpers for home/explore card interactions
- Canonical Tara deep-link and web-link builders for shell launch actions
- Tara session-launch intent parser for shell route-path hydration
- Canonical Tara route builders for meditation launch paths and ritual launch
  paths
- Canonical Tara domain-adapter helpers for metadata, availability,
  continuation, search, and launch resolution

## Usage

```ts
import {
  buildTaraMeditationPath,
  buildTaraRitualPath,
  createTaraDomainAdapter,
} from '@oshun/domain-tara';

const tara = createTaraDomainAdapter({
  baseUrl: 'https://tara.internal',
});

const sessions = await tara.getRecommendedSessions({ limit: 3 });
const meditationPath = buildTaraMeditationPath('morning-calm');
const ritualPath = buildTaraRitualPath('sunrise-reset');
```

## Canonical Model

- `ritual`
  - a structured Tara entry/practice definition
  - launched with `/meditate/ritual/:ritualId`
- `meditation`
  - reusable catalog content
  - launched with `/meditate/session/:meditationId`
- `meditation session`
  - a user progress/execution record
  - resumed with `/meditate/resume/:sessionId`

### Meditation Subtypes

Canonical Tara meditations and meditation-session records also expose a
`meditationSubtype` so shell consumers can distinguish:

- `guided`
- `breathing`
- `sleep`
- `transition`

Subtype-specific metadata is preserved when available:

- `breathPattern` for breathing sessions
- `sleepMode` for sleep sessions
- `transitionTrigger` for transition sessions

### Session Completion And Continuation States

Canonical Tara meditation-session records and continue-session payloads also
normalize two shared state envelopes:

- `completionState`
  - `in_progress`
  - `completed`
  - `ended_early`
  - `error`
- `continuationState`
  - `resume`
  - `restart`
  - `reflect`
  - `replay`

Those helpers keep shell surfaces aligned on:

- when a session should still appear on a continuation rail
- when a completed session should switch to reflection-first afterglow instead
  of a resume affordance
- when a stale or already-reflected session should fall back to replay/history
  semantics instead of remaining a live continuation
- when an abandoned or errored session should restart from the beginning

Use these helpers when building shell-facing session records or continue cards:

- `getCanonicalTaraMeditationSessionStatus()`
- `buildCanonicalTaraSessionCompletionState()`
- `buildCanonicalTaraSessionContinuationState()`

The canonical session record builder,
`buildCanonicalTaraMeditationSessionRecord()`, now attaches:

- `resumePositionSeconds`
- `reflectionState`
- `completionState`
- `continuationState`

### Ritual Template Model

`@oshun/domain-tara` also exposes a canonical Tara ritual-template model for the
ritual engine workstream.

The shared contracts cover:

- `TaraRitualTemplate`
- `TaraRitualStep`
- `TaraRitualTrigger`
- `TaraRitualCompletionPolicy`
- `TaraRitualCompletionState`

Supported canonical ritual step kinds:

- `meditation`
- `breathwork`
- `passage`
- `journaling`
- `nyx_perspective`

Use these helpers when building ritual definitions or evaluating ritual
progress:

- `buildCanonicalTaraRitualStep()`
- `buildCanonicalTaraRitualTrigger()`
- `buildCanonicalTaraRitualCompletionPolicy()`
- `buildCanonicalTaraRitualTemplate()`
- `evaluateTaraRitualCompletion()`

### Ritual Assembly Rules

`@oshun/domain-tara` also exposes canonical ritual-assembly rules so ritual
templates can be composed from available Tara and cross-domain ingredients
without creating surface-specific sequencing logic.

The shared assembly surface includes:

- `TaraRitualAssemblyRule`
- `TaraRitualAssemblyInput`
- `resolveTaraRitualAssemblyRule()`
- `assembleTaraRitualTemplate()`

The rule table encodes:

- which anchor kind to prefer between meditation and breathwork
- when passage, journaling, and Nyx perspective steps are required or optional
- the canonical step ordering for each Tara ritual moment
- optional-step trimming when a duration budget is tighter than the full ritual

### Ritual Scheduling

`@oshun/domain-tara` also exposes a canonical ritual scheduling layer for
time-of-day, continuity-aware, preference-aware reminder planning.

The shared scheduling surface includes:

- `TaraRitualSchedulingPreferences`
- `TaraRitualContinuitySnapshot`
- `TaraRitualSchedulePlan`
- `buildTaraRitualSchedulePlan()`
- `TaraRitualScheduler`

The scheduler supports:

- preferred ritual times and timezone-aware daypart defaults
- continuity-state routing for `resume_window`, `missed_window`,
  `recovery_window`, and `recent_completion`
- quiet-hours-aware reminder deferral
- gentle recovery reminders instead of punitive streak behavior

### Ritual Operations

`@oshun/domain-tara` also exposes ritual operations for humane lifecycle
management after a ritual has been assembled and scheduled.

The shared operations surface includes:

- `editTaraRitualTemplate()`
- `skipTaraRitualStep()`
- `recoverTaraRitualExecution()`
- `rescheduleTaraRitualPlan()`

These helpers are designed to:

- preserve continuity when a step is skipped
- convert misses into recovery windows instead of streak punishment
- support lightweight plan edits and reschedules without rebuilding UI-local
  state by hand

### Ritual Completion Events

`@oshun/domain-tara` also exposes a canonical ritual-completion event layer for
cross-domain consumers.

The shared event surface includes:

- `buildCanonicalTaraRitualCompletionEvent()`
- `projectTaraRitualCompletionEvent()`

These helpers are designed to:

- produce one canonical Tara ritual completion envelope after a ritual reaches a
  real completion state
- attach Arete, Nisaba, and Nyx handoffs using the shared relationship mappers
- project that event into home, activity, search, and recommendation-ready
  records without each downstream system re-deriving the same semantics

### Content Taxonomy

Canonical Tara objects also carry a shared `taxonomy` envelope so every surface
can reason about the same practice metadata instead of inferring UI-local
categories from loose tags.

The shared taxonomy currently includes:

- `mood`
  - `calm`, `grounded`, `focused`, `restorative`, `energizing`, `compassionate`,
    `expansive`
- `themes`
  - `breathwork`, `focus`, `sleep`, `transition`, `compassion`, `movement`,
    `body_scan`, `insight`, `visualization`, `gratitude`
- `durationBand`
  - `micro`, `short`, `medium`, `long`, `extended`
- `tradition`
  - `secular`, `buddhist`, `yogic`, `vedic`, `tibetan`, `advaita`
- `intendedOutcomes`
  - `stress_relief`, `focus`, `sleep_support`, `energy`, `compassion`,
    `clarity`, `emotional_regulation`, `restoration`, `presence`, `recovery`

Use `buildCanonicalTaraContentTaxonomy()` to normalize those values from shared
content signals such as title, summary, duration, category, subtype, tags, or
ritual moment. Use `buildTaraTaxonomySearchTokens()` when a search surface needs
stable query tokens from the canonical taxonomy instead of ad hoc label copies.

### Tara -> Arete Practice Bridge

`@oshun/domain-tara` also exposes a canonical Tara-to-Arete handoff contract via
`resolveTaraAretePracticeRelationship()`.

That helper translates Tara content signals such as:

- `ritualMoment`
- `meditationSubtype`
- `breathPattern`
- `sleepMode`
- `transitionTrigger`

into a shared Arete continuation shape with:

- the mapped Arete practice moment
- the default Arete target path
- the canonical bridge label and CTA
- the canonical `practice_handoff` reason id for cross-domain recommendation
  surfaces

### Tara -> Nisaba Passage Bridge

`@oshun/domain-tara` also exposes a canonical Tara-to-Nisaba passage handoff
contract via `resolveTaraNisabaPassageRelationship()`.

That helper translates the same Tara content signals into a shared Nisaba
continuation shape with:

- the mapped Nisaba study moment
- the default Nisaba passage-oriented target path
- the canonical bridge label and CTA
- the canonical `passage_companion` reason id for Tara-to-Nisaba passage
  recommendation surfaces

### Tara -> Nyx Perspective Bridge

`@oshun/domain-tara` also exposes a canonical Tara-to-Nyx perspective handoff
contract via `resolveTaraNyxPerspectiveRelationship()`.

That helper translates the same Tara content signals into a shared Nyx
continuation shape with:

- the mapped Nyx awe or perspective moment
- the default Nyx highlights or guided-sky target path
- the canonical bridge label and CTA
- the canonical `perspective_handoff` reason id for Tara-to-Nyx recommendation
  surfaces