# Kuan Yin — Event System

> Technical doc 32.16.1.5. Defined in `@kuanyin/sdk-api/event-system.ts`.

Every decision Kuan Yin makes emits a typed domain event. Events are the
integration backbone between engines and external consumers (dashboards,
wellness services, the Aphrodite/Lilith/Hathor/Yemaya domains, and the audit
pipeline).

## Event categories (`EvtSysEventCategory`)

`intervention`, `harm_detection`, `protection`, `rehabilitation`, `circle`,
`merit`, `tier`, `community`, `analytics`, `system`.

## Catalog

| Event                      | Emitted when                                  |
| -------------------------- | --------------------------------------------- |
| `intervention.triggered`   | A friction intervention begins                |
| `intervention.completed`   | Friction completes with an outcome            |
| `harm.detected`            | Harm scoring crosses a category threshold     |
| `protection.activated`     | A shield level is raised for a user/performer |
| `rehabilitation.enrolled`  | A user enrols in a journey                    |
| `rehabilitation.completed` | A journey is completed/certified              |
| `circle.requested`         | A restorative circle is requested             |
| `circle.completed`         | A circle closes with documented outcomes      |
| `merit.awarded`            | Merit is granted for a positive action        |
| `tier.unlocked`            | A privilege tier threshold is crossed         |
| `community.alert`          | Temperature/raid/conflict early warning fires |
| `analytics.report`         | A scheduled dharma report is generated        |

Each event has a builder (`evtDefine*` for canonical definitions, `evtCreate*`
for instances) that validates payload shape and severity. Severity- and
category-indexed getters (`getEvt*BySeverity`, `getEvt*ByCategory`) support
fan-out routing.

## Event bus

```ts
import { evtImplementEventBusIntegration } from '@kuanyin/sdk-api';

const bus = evtImplementEventBusIntegration({
  enableMiddleware: true,
  routingStrategy: 'topic', // direct | topic | fanout | content_based
  maxRetries: 3,
  deadLetterEnabled: true,
  batchSize: 64,
  compressionEnabled: true,
});
// bus.totalHandlers, bus.routingEfficiency, bus.healthScore,
// bus.latencyP50Ms / latencyP99Ms, bus.deadLetterQueueSize
```

The bus reports throughput and P50/P99 latency so its own health can be watched
on the same dashboards as the engines. Dead-lettering captures undeliverable
events for replay.

## Replay

```ts
import { evtCreateEventReplaySystem } from '@kuanyin/sdk-api';

const replay = evtCreateEventReplaySystem({
  replayFrom: '2026-05-31T00:00:00Z',
  replayTo: '2026-05-31T01:00:00Z',
  eventCategoryFilter: 'harm_detection', // or null for all
  maxEvents: 500,
  speedMultiplier: 4,
  includeTimeTravelSnapshots: true,
});
// replay.totalEventsReplayed, replay.replayFidelity, replay.gapsDetected
```

Replay is used for incident forensics (reconstruct exactly what the system saw
and decided), regression testing against historical streams, and onboarding new
downstream consumers against real traffic shapes.

## Delivery guarantees

Webhooks (`sdkCreateWebhookHandling`) deliver events to external URLs with HMAC
signing and retry policy; in-process subscribers receive events synchronously
through the bus. Consumers should treat events as **at-least-once** and dedupe
on event id. See `06-integration-guides.md` for wiring the cross-domain
consumers.
