# @oshun/domain-arete

Typed Arete domain adapter package for the OSHUN shell.

## Included

- Arete API adapter contracts (`AreteApiAdapter`)
- Canonical shell-facing Arete adapter contract (`AreteDomainAdapter`)
- Canonical Arete object model contracts for habits, goals, routines, reviews,
  and coaching summaries
- Canonical humane streak-recovery helpers for Arete habits
- Canonical friction logging and intervention taxonomy helpers
- Canonical coaching-summary surface contracts for cards and assistants
- Canonical assistant accountability and humane plan-recovery flow helpers
- Canonical shared concept-graph linkages for Arete themes
- Canonical save/share/export artifact policies and export builders for Arete
  workspaces
- Canonical Arete-to-Tara ritual relationship helpers
- Canonical Arete-to-Nisaba study relationship helpers
- Canonical Arete-to-Veritas habit-science grounding helpers
- Goal, habit, journal, coach, balance, reminder, and streak response models
- Adapter factory (`createAreteDomainAdapter`) with typed error handling
- Home/Explore Arete card model builders for OSHUN shell surfaces
- Arete launch-action mapping helpers for shell card interactions
- Canonical Arete deep-link and web-link builders
- Canonical Arete adapter helpers for metadata, availability, continuation,
  search composition, launch resolution, active-goal lookup, and saved-item
  toggling

## Usage

```ts
import { createAreteDomainAdapter } from '@oshun/domain-arete';

const arete = createAreteDomainAdapter({
  baseUrl: 'https://arete.internal',
});

const goals = await arete.getGoals({
  userId: 'user-123',
  status: 'active',
});
```

## Canonical Object Model

The package also exposes a shell-safe canonical object model for the Arete
planning domain:

- `AreteHabit`
- `AreteGoal`
- `AreteRoutine`
- `AreteReview`
- `AreteCoachingSummary`

Normalization helpers such as `buildCanonicalAreteHabit`,
`buildCanonicalAreteGoal`, and `buildCanonicalAreteRoutine` clamp progress,
dedupe references, and sort embedded collections so later OSHUN Arete features
reuse one stable contract.

## Humane Streak Recovery

`@oshun/domain-arete` also exposes canonical streak-recovery helpers via
`evaluateAreteHabitRecovery()` and `applyAreteHabitRecoveryCompletion()`.

Those helpers turn canonical habit schedule and streak-policy data into one
shared recovery contract with:

- conservative missed-window counting by cadence
- explicit grace-window, freeze-window, repair-window, and fresh-restart stages
- humane copy and action labels that avoid guilt-based streak framing
- honest restart semantics that archive prior momentum instead of erasing it
- completion helpers so later cards, assistants, and analytics can reuse the
  same continuity logic

## Friction And Intervention Taxonomy

`@oshun/domain-arete` also exposes canonical friction taxonomy helpers via
`buildCanonicalAreteFrictionLog()`, `buildAreteInterventionRecommendations()`,
and `summarizeAreteFrictionLogs()`.

Those helpers define one shared vocabulary for:

- friction phases such as cue, entry, execution, review, and recovery
- friction categories such as time fragmentation, recovery debt, emotional
  resistance, and scope overload
- intervention kinds such as scope reduction, cue redesign, schedule protection,
  recovery support, and momentum rebuild
- prioritized intervention recommendations so later Arete cards, assistants, and
  planning surfaces reuse the same coaching taxonomy

## Coaching Summary Surface Contracts

`@oshun/domain-arete` also exposes coaching-summary surface helpers via
`buildAreteCoachingSummaryShellModel()`.

That helper converts the canonical coaching-summary object into one shell-facing
contract with:

- a card-ready coaching summary model
- an assistant-ready brief with seeded prompt, continuity summary, and talking
  points
- optional friction-summary and streak-recovery composition so later Arete cards
  and assistant handoffs reuse one summary surface model

## Assistant Accountability And Plan Recovery Flows

`@oshun/domain-arete` also exposes assistant accountability helpers via
`buildAreteAssistantAccountabilityFlows()`.

That helper turns the active review, selected goal, selected routine, current
decision statuses, and anchor completion state into one shared assistant handoff
layer with:

- an accountability brief that turns the next commitment into a witnessed thread
- a humane recovery brief that rebuilds the next 48 hours without guilt-based
  framing
- deduplicated intervention recommendations derived from the canonical friction
  taxonomy
- stable assistant source ids and shell-safe detail rows for UI surfaces and
  analytics

## Shared Concept Graph Linkages

`@oshun/domain-arete` also exposes shared concept-graph helpers via
`inferAreteThemeConceptIds()`, `buildAreteThemeConceptGraphReflections()`, and
`buildAreteThemeConceptGraphThreads()`.

Those helpers turn Arete themes, practice moments, practice areas, and journal
threads into a shared concept-link layer with:

- stable Arete theme concept ids such as focus protection, humane recovery, and
  study clarity
- linked Nisaba passages and Veritas claims for each active theme
- linked Arete reflection threads so related entries can be reopened as one
  continuity line instead of isolated notes
- shell-safe launch paths and reason ids for later UI surfaces and analytics

## Artifact Save, Share, And Export Policies

`@oshun/domain-arete` also exposes canonical artifact rules via
`getAreteArtifactPolicy()`, `buildAretePlanReviewExport()`,
`buildAreteJournalReflectionExport()`, and `buildAreteProgressMapExport()`.

Those helpers define one shared policy layer for:

- which Arete workspace artifacts can be saved, shared, or exported
- portable markdown export payloads for planning briefs, reflection drafts, and
  progress analyses
- consistent product wording so later Arete routes do not drift on artifact
  support expectations

## Arete -> Tara Ritual Bridge

`@oshun/domain-arete` also exposes a canonical Arete-to-Tara relationship
contract via `resolveAreteTaraPracticeRelationship()`.

That helper translates Arete planning signals such as:

- `practiceMoment`
- `objectKind`
- `goalCategory`
- `habitCategory`
- `reviewKind`
- `practiceAreas`

into a shared Tara ritual-support shape with:

- the mapped Tara ritual moment
- a canonical Tara ritual id and launch path
- the bridge label and CTA
- the canonical `ritual_support` reason id for Arete-led cross-domain
  recommendation surfaces

## Arete Plan/Review Tara Suggestions

`@oshun/domain-arete` also exposes `buildAretePlanReviewTaraSuggestions()` for
review-oriented Arete workspaces.

That helper turns the active review context, selected goal, selected routine,
and decision pressure into a deduplicated Tara ritual suggestion rail with:

- review-closing ritual support
- focus or study ritual support for the currently selected goal or routine
- recovery-oriented ritual support when the review state is carrying pressure

## Arete -> Nisaba Study Bridge

`@oshun/domain-arete` also exposes a canonical Arete-to-Nisaba relationship
contract via `resolveAreteNisabaStudyRelationship()`.

That helper translates Arete planning signals such as:

- `practiceMoment`
- `objectKind`
- `goalCategory`
- `habitCategory`
- `reviewKind`
- `practiceAreas`

into a shared Nisaba study-companion shape with:

- the mapped Nisaba study moment
- the default Nisaba target path
- the bridge label and CTA
- the canonical `study_companion` reason id for Arete-led study surfaces

For program-oriented Arete surfaces, the package also exposes
`buildAreteProgramNisabaPrompts()`, which derives deduplicated Nisaba study
prompts from relevant goals and routines so learning-oriented Arete lanes can
launch into grounded Nisaba reading or study flows without bespoke mapping logic
in the UI.

## Arete -> Veritas Habit Grounding Bridge

`@oshun/domain-arete` also exposes a canonical habit-science grounding bridge
via `resolveAreteVeritasHabitScienceGrounding()` and
`buildAreteVeritasHabitScienceGroundings()`.

Those helpers define one shared Veritas handoff layer for Arete habit claims
that benefit from grounding, including:

- cue-routine-reward habit loop language
- four-laws behavior-design shorthand
- identity-based habit framing
- streak-protection and grace-day claims
- habit stacking explainers

Each grounding relationship carries one stable shell-safe contract with:

- a canonical grounding id for UI data attributes and analytics
- whether the handoff is a Veritas claim or explainer
- the target Veritas path
- a concise summary and CTA
- the canonical `habit_science_grounding` reason id