The Vectry data model: five primitives, one causal graph

Vectry’s entire surface — SDKs, ingest API, explanations, anomaly detection — reduces to five primitives organized in four layers: observation → execution → semantics → diagnostics. This post walks through each one.

Event (observation)

The atomic unit. An Event represents a single action, change or signal captured within a system, and it always answers four questions by schema, not by convention:

• Who — actor_id + actor_type (user, system, ai or device)
• What — an embedded operation object
• Where — organization_id and app_id (multi-tenant by design)
• When — full audit timestamps

The operation is the heart of the grammar. It names the verb (created, updated, deleted, restored, patched, merged, duplicated, signaled, triggered, evaluated), the system_domain, the system_entity and the exact instance affected. When the operation mutates state, it carries a structured diff — original vs updated, field by field.

A readable namespace like inventory.item.updated gives every event a human-friendly identity for filtering and streams.

Trace (execution)

A Trace groups the events that belong to one coherent unit of behavior around one entity — a reservation moving through booking, a quote under negotiation. It records the entity coordinates (system_domain, system_entity, system_entity_id), a start and end timestamp, and the primary actor. Traces answer: what happened to this entity during this process?

CausalThread (execution)

Threads are the cross-system layer: one CausalThread links many traces into the broader storyline of an entity, and closes with an outcome — approved, error, abandoned. When an incident spans four services, the thread is what lets you walk it as one narrative.

EventExplanation (semantics)

The why. Given one event, an EventExplanation stores the reconstructed chain of causes — a caused_by array of causative events with their timestamps and payload snapshots — plus a generated, human-readable narrative:

“The quote was rejected because the item was previously marked as expired by the system.”

It is an intelligence-driven audit layer, generated when deeper causal insight is needed, and persisted as a first-class record.

Anomaly (diagnostics)

Deviations are recorded at the level where they occur — event, trace or causal_thread — with the expected pattern, the actual pattern and a deviation_score. Each anomaly can reference the EventExplanation that reasons about it, so a spike is never just a number: it links to the story behind it.

Why this shape

Two properties fall out of this model. Attribution is total: every record carries actor, tenant and audit metadata. Causality is first-class: threads and explanations are written into the graph, not reverse-engineered from timestamps at query time. That is the difference between observability and explanation.