AI Gateway Service — Event Schemas
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 04 event-driven · standards/NAMING.md
All events follow the platform CloudEvents 1.0 envelope. Event type format: ai_gateway.{aggregate}.{event}.v{N}. NATS subject = event type. All payloads are PHI-safe by default (no raw prompts, no raw outputs, no free-text PHI). DPIA-approved tenants may enable an opt-in secure-retention payload on a separate subject (ai_gateway_secure.*) subject to legal review.
1. Produced events
| Event type | Aggregate | Retention | Trigger | Payload fields |
|---|---|---|---|---|
ai_gateway.assist.requested.v1 | AIDecision | 7y | Auth + quota consumed | correlationId, decisionId, tenantId, actorId, featureKey, resourceType, residency, inputChars, hasInstructions |
ai_gateway.assist.completed.v1 | AIDecision | 7y | Provider returned, provenance stamped | correlationId, decisionId, tenantId, actorId, featureKey, provenanceId, provider, modelVersion, promptTemplate.key/version, latencyMs, moderation.input, moderation.output, hitlRequired |
ai_gateway.assist.failed.v1 | AIDecision | 7y | Any failure path | correlationId, decisionId?, tenantId, actorId, featureKey, reasonCode, provider?, retryable |
ai_gateway.decision.created.v1 | AIDecision | 7y | Decision persisted as draft | decisionId, tenantId, featureKey, state, consumerService, provenanceId |
ai_gateway.decision.hitl_queued.v1 | AIDecision | 7y | Draft requires HITL | decisionId, tenantId, featureKey, assignmentPolicy, queuedAt |
ai_gateway.decision.accepted.v1 | AIDecision | 7y | Reviewer accepted or owner finalised | decisionId, tenantId, featureKey, provenanceId, acceptedBy, acceptedByRole, targetResource |
ai_gateway.decision.rejected.v1 | AIDecision | 7y | Reviewer rejected / timeout | decisionId, tenantId, featureKey, rejectedBy, rejectionReason |
ai_gateway.moderation.flagged.v1 | ModerationFinding | 3y | Classifier above threshold | decisionId, tenantId, featureKey, stage (input|output), categories[], verdict, thresholds |
ai_gateway.provider.degraded.v1 | ProviderRoutingRule | 1y | Circuit breaker opened | tenantId?, provider, featureKey?, consecutiveErrors, lastErrorCode, detectedAt |
ai_gateway.provider.recovered.v1 | ProviderRoutingRule | 1y | Circuit closed again | provider, downtimeMs, recoveredAt |
ai_gateway.quota.exceeded.v1 | TenantQuota | 1y | Quota breach | tenantId, featureKey, windowSec, limit, attemptedAt |
ai_gateway.routing_rule.updated.v1 | ProviderRoutingRule | 7y | Admin changed rule | tenantId?, featureKey, changes, updatedBy |
ai_gateway.prompt_template.published.v1 | PromptTemplate | 7y | New version published | templateKey, version, guardrailsHash, publishedBy |
2. Consumed events
| Subject | Source | Reaction |
|---|---|---|
identity.user.disabled.v1 | identity-service | Revoke cached tokens, pending HITL review reassignment |
tenant.suspended.v1 | tenant-service | Disable new assists for tenant; existing reviews retained |
config.feature_flag.updated.v1 | config-service | Invalidate per-feature cache |
config.provider_matrix.updated.v1 | config-service | Rebuild routing in memory |
3. Envelope (CloudEvents 1.0)
{
"specversion": "1.0",
"type": "ai_gateway.assist.completed.v1",
"source": "ghasi/ai-gateway-service",
"id": "uuid",
"time": "ISO8601",
"subject": "dec_01H...",
"datacontenttype": "application/json",
"tenantid": "ten_...",
"actorid": "usr_...",
"correlationid": "uuid",
"data": { "...as table above..." }
}
4. JetStream configuration
| Stream | Subjects | Retention | Storage | Replicas |
|---|---|---|---|---|
ai-gateway-events | ai_gateway.* | limits — 7y | file | 3 |
ai-gateway-ops | ai_gateway.provider.*, ai_gateway.quota.* | limits — 1y | file | 3 |
ai-gateway-dlq | ai_gateway.dlq.* | manual | file | 3 |
5. Schema versioning
- All schemas live under
packages/@ghasi/event-envelope/schemas/ai_gateway/. - Breaking changes emit a new version suffix (
.v2); both versions run for ≥1 release. - Contract tests validate payload shape on publish and consume.
6. PHI redaction policy
Default subjects must not contain: raw instructions, raw draftText, patient names, addresses, free-text notes, or medication strings. Metrics allowed: character counts, token counts, category scores, resource references (IDs only).