# OSHUN Entitlement Schema

Status: Active  
Owner: OSHUN Platform Engineering  
Last Updated: February 16, 2026  
Related: `libs/oshun/auth/src/entitlements.ts`, `OSHUN_APP_TODOS.md`

## Purpose

Define one shared entitlement schema for OSHUN shell and adapters:

- tier definitions (`free`, `pro`, `premium`)
- per-domain minimum access tiers
- per-feature tier gates and optional usage limits
- deterministic evaluation helpers for domain/feature access

## Tier Model

| Tier      | Order | Intended Access                            |
| --------- | ----- | ------------------------------------------ |
| `free`    | 0     | baseline access across all domains         |
| `pro`     | 1     | advanced features and higher usage limits  |
| `premium` | 2     | full access and unlimited premium features |

## Domain Policies

The schema currently defines policies for:

- `tara`
- `veritas`
- `nyx`
- `arete`

Each policy includes:

- `minimumTier` for domain-level entry
- `features[]` where each feature has:
  - `featureKey`
  - `minimumTier`
  - `limit` (`number | null`)
  - `period` (`daily | monthly | lifetime`)

## Evaluation Contracts

`libs/oshun/auth/src/entitlements.ts` exposes:

- `evaluateDomainAccess(...)`
- `evaluateFeatureAccess(...)`
- `getEffectiveTierForDomain(...)`
- `hasTierAccess(...)`
- `getDomainEntitlementPolicy(...)`
- `listDomainEntitlementPolicies(...)`

Evaluation reasons are normalized to:

- `allowed`
- `insufficient_tier`
- `domain_suspended`
- `feature_not_found`
- `limit_exceeded`

## Notes

- This schema is the canonical source for shell-side entitlement checks.
- Server-side authorization remains authoritative; client checks are UX gates.
- Future tiers (for example `student`/`family`) should be added by extending:
  - tier order
  - tier definitions
  - domain feature policy mappings
