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#
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:
guidedbreathingsleeptransition
Subtype-specific metadata is preserved when available:
breathPatternfor breathing sessionssleepModefor sleep sessionstransitionTriggerfor transition sessions
Session Completion And Continuation States#
Canonical Tara meditation-session records and continue-session payloads also normalize two shared state envelopes:
completionStatein_progresscompletedended_earlyerror
continuationStateresumerestartreflectreplay
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:
resumePositionSecondsreflectionStatecompletionStatecontinuationState
Ritual Template Model#
@oshun/domain-tara also exposes a canonical Tara ritual-template model for the
ritual engine workstream.
The shared contracts cover:
TaraRitualTemplateTaraRitualStepTaraRitualTriggerTaraRitualCompletionPolicyTaraRitualCompletionState
Supported canonical ritual step kinds:
meditationbreathworkpassagejournalingnyx_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:
TaraRitualAssemblyRuleTaraRitualAssemblyInputresolveTaraRitualAssemblyRule()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:
TaraRitualSchedulingPreferencesTaraRitualContinuitySnapshotTaraRitualSchedulePlanbuildTaraRitualSchedulePlan()TaraRitualScheduler
The scheduler supports:
- preferred ritual times and timezone-aware daypart defaults
- continuity-state routing for
resume_window,missed_window,recovery_window, andrecent_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:
moodcalm,grounded,focused,restorative,energizing,compassionate,expansive
themesbreathwork,focus,sleep,transition,compassion,movement,body_scan,insight,visualization,gratitude
durationBandmicro,short,medium,long,extended
traditionsecular,buddhist,yogic,vedic,tibetan,advaita
intendedOutcomesstress_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:
ritualMomentmeditationSubtypebreathPatternsleepModetransitionTrigger
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_handoffreason 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_companionreason 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_handoffreason id for Tara-to-Nyx recommendation surfaces