# Kuan Yin — Database Schema

> Technical doc 32.16.1.4. Defined in `@kuanyin/database` (`schemas.ts`,
> `migrations.ts`, `repositories.ts`, `seeds.ts`).

Kuan Yin persists to the domain-isolated `hathor`/`kuanyin` Postgres instance
(pgvector-enabled). The schema is authored as typed entities in `schemas.ts`;
`migrations.ts` carries the DDL, indexes, partitions, materialized views, and
triggers; `repositories.ts` exposes typed repository classes used by the engines
and the SDK.

## Entity groups (25 tables)

**Identity & reputation**

- `KuanYinUserProfile` — per-user extension (Buddha-nature attributes, tier,
  protection level)
- `MeritLedger` — append-only karma entries (`pointsEarned`, `streakBonus`,
  `qualityBonus`, `runningTotal`, `tierAtTime`, `decayApplied`)
- `TrustScore` — composite trust with decay tracking
- `AccountabilityCommitment` — repair commitments + deadlines

**Moderation & harm**

- `InterventionRecord` — friction history (`interventionType`, `harmScore`,
  `triggerCategory`, `effectiveness`, `userResponse`, `escalated`)
- `HarmIncident`, `BehaviorPattern`, `EmotionalStateLog`, `CascadeIncident`,
  `BoundaryViolation`, `ParasocialAlert`

**Rehabilitation**

- `RehabilitationJourney`, `ShadowWorkProgress`, `RestorativeCircle`,
  `CircleOutcome`, `ReintegrationMilestone`, `PerspectiveShiftExercise`,
  `EmpathyTrainingProgress`

**Protection, community & governance**

- `PerformerProtectionConfig`, `MindfulFrictionConfig`,
  `CommunityHealthSnapshot`, `DharmaMetric`, `AppealRecord`, `ModeratorAction`,
  `AuditLog`

## Indexing & performance

`migrations.ts` adds indexes for the hot queries: harm-pattern lookups, trust
score reads, performer-protection queries, rehabilitation progress, community
health analytics, merit leaderboards, time-series emotional data, behavioural
pattern matching, and full-text content search. High-volume intervention logs
are partitioned; dharma dashboards read from materialized views; trust score and
merit ledger maintenance run via triggers.

## Repository layer

`repositories.ts` exposes one class per aggregate, each an in-memory-backed,
typed CRUD + domain-query surface (the same interface a Drizzle/Prisma adapter
implements in production):

`UserKuanYinRepository`, `MeritRepository`, `InterventionRepository`,
`RehabilitationRepository`, `CircleRepository`, `ProtectionRepository`,
`IncidentRepository`, `PatternRepository`, `HealthRepository`,
`AnalyticsRepository`, `AuditRepository`, `CacheRepository`, `SearchRepository`,
`TimeSeriesRepository`, `GraphRepository`.

Representative methods:

```ts
const merit = new MeritRepository();
merit.create(entry); // append a ledger row
merit.calculateRunningTotal(userId); // Σ points + bonuses − decay
merit.getLeaderboard(10); // opt-in ranking
merit.applyDecay(userId, 0.1); // inactivity decay

const cache = new CacheRepository();
cache.setWithTTL(key, value, ttlMs, tags);
cache.invalidateByTag('user-a'); // returns count removed
cache.invalidateByPrefix('trust:');
cache.getStats(); // hits, expired, avg TTL
```

## Seeds

`seeds.ts` provides baseline data for harm categories, intervention templates,
rehabilitation journeys, shadow-work modules, perspective-shift exercises,
empathy modules, mindful-friction prompts, Samma Vaca reflection questions,
cognitive reframe suggestions, and community-health baselines — enough to run
the engines end-to-end in development without external dependencies.
