Event schema

Every journal record is an immutable entry. The wire format is api/event/v1. This document describes the fields, the record types, and how keys and hashes are derived.

Record fields

Field	Purpose
cluster_id	Separates resource version and UID domains; one per physical cluster
stream_id	Identifies group, version, resource, namespace, and selector
event_id	Deterministic deduplication key
ingest_sequence	Local storage order (ascending); returned in this order
observed_at	Collector observation time
watch_type	Original event type (ADDED, MODIFIED, DELETED, BOOKMARK, ERROR)
synthetic	True for baseline events
resource	Group, version, kind, namespace, name, UID, resource version
object_hash	Fast equality and deduplication
object	Raw or faithfully preserved payload (JSON)
provenance	Optional audit correlation

The raw watch payload is kept separate from normalized fields. This preserves unknown CRD fields. Never re-serialize the object into a lossy normalized shape.

Record types

The journal stores event records plus these special records:

Type	Meaning
event	A watch event (ADDED, MODIFIED, DELETED)
baseline	A list result (initial or post-relist)
gap	Continuity was lost (for example, a 410 Gone response)
coverage_change	A resource became unavailable or was newly discovered
audit_correlation	Optional request provenance matched from audit logs
snapshot	A materialized set of stream boundaries
checkpoint	Progress marker advanced by a bookmark

The corresponding record type constants in internal/event are: TypeEvent, TypeBaseline, TypeGap, TypeCoverageChange, TypeAuditCorrelation, TypeSnapshot, and TypeCheckpoint. The watch types are: WatchAdded, WatchModified, WatchDeleted, WatchBookmark, and WatchError.

event_id derivation

The field event_id is the deterministic deduplication key. The derivation is:

EventID(stream, resource, watchType, observedAt) -> string

The inputs are the stream identity, the resource reference, the watch type, and the observed time. The same key is recomputed for a redelivered event, for example after a reconnect or a crash before the checkpoint. Re-application is therefore idempotent. This makes at-least-once ingestion safe. See ../consistency/consistency.md for the ingestion guarantee.

object_hash

The function ObjectHash(objectJSON) returns a fast equality and deduplication hash over the raw object payload. It lets consumers detect that a MODIFIED event did not change the object. It lets the store collapse no-op writes. It is not a cryptographic commitment. Treat it as a performance and equality helper only.

Provenance

The field provenance is optional. When audit logs are available, an audit event is correlated to a stored event by cluster, namespace, name, UID, and resource version. It is recorded as a TypeAuditCorrelation record that references the field event_id. Audit identity is available only through this optional correlation. A watch event itself never contains the actor who made the change.

Versioning

The package api/event/v1 is the public wire format. Internal packages stay private until the schema and replay contract stabilize. The manifest used by the object-storage segment layout records a schema version alongside the redaction policy version. Do not change api/event/v1 without a coordinated schema bump. Consumers of the journal and replay contract depend on it.

3.7 KiB Raw Blame History