Core Events
Canonical KYA-OS audit event families and lifecycle rules
Core Audit Events
The v1 producer-event schema defines a closed event vocabulary. Event names use stable dot-separated identifiers and carry a matching typed details family and phase.
Event families
| Family | Representative events |
|---|---|
| Session | session.established, session.rejected, session.expired, session.replay_rejected |
| Tool | tool.call.started, tool.call.completed, tool.call.failed, tool.call.denied, tool.call.challenged |
| Proof | proof.generated, proof.verified, proof.rejected |
| Delegation | delegation.issued, delegation.verified, delegation.rejected, delegation.revoked, delegation.cascade_revoked, delegation.outbound_attached |
| Authorization | authorization.evaluated, authorization.approved, authorization.denied, authorization.step_up_required, grant.used |
| Consent and credentials | consent.requested, consent.approved, consent.denied, credential.required, credential.verified, credential.failed |
| Configuration and keys | key.rotated, policy.changed, configuration.changed, integrity_suite.transitioned |
| Ledger | ledger.epoch.started, ledger.epoch.transitioned, checkpoint.created, checkpoint.anchored, checkpoint.anchor_failed, evidence.disposed, projection.reconciled |
| Administration | audit.source_high_water, audit.accessed, audit.exported, legal_hold.applied, retention.executed |
See the live event schema for the normative enum and per-family detail requirements.
Lifecycle invariant
Every instrumented operation with a start phase emits:
- one stable
*.startedor request event before the side effect; and - exactly one terminal event for every return, throw, denial, challenge, timeout, cancellation, or retry-exhaustion branch.
For tool calls, terminal events are completed, failed, denied, or challenged. They share correlation and causation identity with the start event.
Record intent before side effects
For side-effecting tools, commit or durably claim the intent before invoking the side effect. A crash between the business transition and audit enqueue must roll back both or leave recoverable, idempotent work—not an unaudited action.
Identity and correlation
eventIdis stable across byte-identical retries.sourceId,sourceSequence, andpreviousSourceEventDigestdescribe the producer's durable order.correlationIdjoins a request or workflow.causationIdpoints to the event that caused the current event.session.ref,actor,responsibleParty, andresourceuse privacy-aware party references.- foreign MCP metadata and existing proof metadata remain intact; audit receipt metadata is additive.
Outcomes and reasons
Use the closed outcome vocabulary: succeeded, failed, denied, challenged, or unknown. Put a stable machine-readable reason code in reason.code; sensitive messages, request bodies, stack traces, credentials, and policy inputs belong in encrypted evidence.
Do not infer success from a missing terminal event. A missing terminal is an operational gap that must remain visible to reconciliation and monitoring.