Eve library

Kuan Yin — Event System

Guide

Revision 1

On this page

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.