Events

Partial: the event_type registry and the richer occurrence are built

ADR-0063 confirms this separation. The event_type registry is built: list, get, and custom-type create/update/delete over /event-types, seeded official types (call-started, command-issued), operator-extensible, official rows read-only, mirroring the sample catalogs. The event occurrence carries origin (caught/caused/derived/scheduled) plus the ADR-0066 lineage columns (source_event_id, source_log_line_id, derived_by_rule_id) and the correlation_id trace. Two producers are built: the native caught path (a component publishing an occurrence on the wire’s own event lane, an xAPI event or SNMP trap, validated against event_type and landed with origin=caught, under the same owner-confinement and reject-not-project as a metric or property) and the caused origin (a command records a caused command-issued event on issue, #396). Raw log lines are a separate ingest lane, not events (ADR-0066): the component-only log_line table, the node-owned node_log self-log table beside it (ADR-0079), their reads, and the first producer are built (a node ships its own operational log lines as untyped LogLines; the ingest consumer lands them in node_log, with a console Self-logs panel on the node blade). The derivation rules that turn a log line into a registered event are directional, along with the event_rule engine, the derived/scheduled producers, the alarm edge, and the CDC publisher.

An event is our semantic assertion that something happened, in our vocabulary: a discrete, point-in-time occurrence the action layer reacts to, owned through the same exclusive-arc as a sample. It is not a sample (the has-a-value-now razor): samples are what rules read, events are what event rules produce. The rules live on calculations; alarms and the responding actions on alarms and actions.

The event_type registry

A sample and an event are different shapes, so each gets its own registry: the two sample catalogs (metric_type, property_type) for samples, event_type for events. event_type describes every event key: (name, label, payload_schema, official, ...), with the official boolean (shipped-canonical versus org-local) as the built governance column; the fuller template / org / official scope ladder is future design, shared with the sample registry (key scope). Declaring event types (call-started, cable-unplugged, command-issued) gives events a known schema, makes them inspectable, and is what a derivation rule targets when turning a raw log line into a registered event; raw lines live untyped in the log_line lane until then, and most never become events.

Events: caught, caused, derived, scheduled

An event arrives one of four ways; none is auto-manufactured from a value flip (a transition is already two consecutive sample rows, derivable by query).

1. caught: a component publishes a structured occurrence natively (an xAPI Event channel, a webhook, an SNMP trap).
2. caused: we issued a command, recorded as an event; this is what opens an intended sample.

The derived and scheduled producers: the event_rule (ADR-0050), log derivation (#410), and the clock (#419)

3. derived: an event rule fuses signals into an operator-meaningful fact (“codec in-call + traffic spike + room booked, so meeting started”), or turns a raw log line from the log_line lane into a registered event, inferred without instrumenting the control system.
4. scheduled: the clock fired a schedule. A schedule fire is an event with origin=scheduled, manufactured by the clock (a leader-elected singleton on a NATS KV CAS lock); there is no separate schedule log table. So action_rule subscribes to events uniformly (schedule to event to action: digests, synthetic checks, SLA resets are all schedule fires an action subscribes to).

Caught/caused/derived/scheduled is the event’s origin, a small vocabulary on the event table, not the same enum as sample provenance. What keeps an event-driven system from rotting: events are declared (registered keys) and rules are inspectable (the blast-radius preview in the UI).

Storage

The event row is the semantic-occurrence log; event_type is its key registry. Physical layout (partitioning, the owner arc, lineage) lives on storage.

The event_rule write path and the CDC publisher (ADR-0050; the CDC lane is #430)

An event is born in a Postgres transaction, on the record lane: a firing event_rule writes the event row and its paired alarm transition in one transaction (serialized per (event_rule, owner)), and the CDC publisher fans the committed change onto JetStream for the action_rule consumers (no dual-write). The opposite lane from samples, which live on NATS and sink to PG asynchronously (samples).

There is no alarm_id column today; the event-carries-its-alarm edge is design direction. The lineage columns (ADR-0066) name what produced the event; the flat correlation_id threads the causal chain.

event (telemetry): generated from the migrated schema by make gen

Column	Type	Constraints	Notes
id	bigint	PK
ts	timestamp with time zone	not null, default now()
owner_kind	text	not null
instance	text	not null, default ''::text	The sub-entity the occurrence is about, when the owner is not enough
message	text	not null, default ''::text
attributes	jsonb
provenance	text	not null, default 'observed'::text
source	text	not null, default ''::text
source_rule	text
source_rule_version	bigint
component_id	uuid	FK → component.id
system_id	uuid	FK → system.id
location_id	uuid	FK → location.id
node_id	uuid	FK → node.principal_id
event_type_id	uuid	FK → event_type.id, not null	The registered key this occurrence asserts
origin	text	not null, default 'caught'::text	How the event arrived: caught, caused, derived, or scheduled
source_event_id	bigint	FK → event.id	Lineage: the parent event, when one event caused another
correlation_id	text		Threads the causal chain flat, across lineage hops
source_log_line_id	bigint	FK → log_line.id	Lineage: the raw log line a derivation rule promoted
derived_by_rule_id	uuid		Lineage: the rule that did the deriving; a natively-caught event has none

CHECK constraints and unique indexes on event

• event_origin_check: CHECK ((origin = ANY (ARRAY['caught'::text, 'caused'::text, 'derived'::text, 'scheduled'::text])))
• event_owner_arc_check: CHECK ((((owner_kind = 'component'::text) AND (component_id IS NOT NULL) AND (system_id IS NULL) AND (location_id IS NULL) AND (node_id IS NULL)) OR ((owner_kind = 'system'::text) AND (system_id IS NOT NULL) AND (component_id IS NULL) AND (location_id IS NULL) AND (node_id IS NULL)) OR ((owner_kind = 'location'::text) AND (location_id IS NOT NULL) AND (component_id IS NULL) AND (system_id IS NULL) AND (node_id IS NULL)) OR ((owner_kind = 'node'::text) AND (node_id IS NOT NULL) AND (component_id IS NULL) AND (system_id IS NULL) AND (location_id IS NULL))))
• event_owner_kind_check: CHECK ((owner_kind = ANY (ARRAY['component'::text, 'system'::text, 'location'::text, 'node'::text])))
• event_provenance_check: CHECK ((provenance = ANY (ARRAY['observed'::text, 'calculated'::text, 'intended'::text, 'declared'::text])))

event_type (telemetry): generated from the migrated schema by make gen

Column	Type	Constraints	Notes
id	uuid	PK, default uuidv7()
name	text	not null
label	text
description	text	not null, default ''::text
payload_schema	jsonb		The JSON Schema an occurrence of this key promises its attributes satisfy
official	boolean	not null, default false	Shipped-canonical versus org-local; official rows are read-only
registered_at	timestamp with time zone	not null, default now()

CHECK constraints and unique indexes on event_type

• event_type_name_key: CREATE UNIQUE INDEX event_type_name_key ON public.event_type USING btree (name)

Related: calculations (the event_rule), alarms and actions, samples, and the glossary.