Eve library

@oshun/domain-tara

Other

Revision 1

On this page

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