Skip to content
Network/Access THE DEFINITIVE GUIDE

Data Model

Status: ✅ Decided — grounded in ADR-0004 and ADR-0007

The kernel’s data model answers one question: what does a domain fact look like, and how much provenance does it carry? The answer is layered: every fact has a type-safe value, every write is audited, and some facts — the contested ones — carry full multi-source provenance machinery.

Entities and Objects

An Entity is the kernel’s named, identity-bearing thing. Every entity has a type declared in a Realm (e.g. network.FiberSpan, projects.WorkPackage) and a client-generated UUID as its stable identity. Client-generated identity is a non-negotiable kernel invariant — it supports offline action queuing and reconnect deduplication without server-sequence coordination (ADR-0013).

“Object” is the term for an entity instance as it appears in the Serving Store — the current projected state of an entity, ready for reads.

Traits and Attributes

A Trait is a named set of Attributes — a reusable schema fragment that can be applied to multiple Entity types. Attributes are the fields on a Trait. Each Attribute has exactly one Value Type that governs its shape, validation, storage mapping, and SDK codegen.

Traits allow cross-cutting schemas (e.g. geo.Locatable, evidence.EvidenceBacked) to be defined once and composed into Entity types across multiple Realms.

Statements and opt-in backing

Not every attribute needs full multi-source provenance. The default attribute is a plain value, mutated directly by an Action and audited via the event log. This is sufficient for facts that have exactly one authoritative source — workflow status, system timestamps, comments.

A Statement is the mechanism for facts that have multiple independent sources and may disagree: geometry reported by GIS vs. geometry measured in a field survey, for example. A Statement carries seven dimensions: source, actor, evidence, confidence, validTime, transactionTime, and authority. Conflicting statements from different sources are retained; the Projection Engine resolves them using Authority rules to select the current serving value.

Statement-backing is opt-in per Attribute, declared in schema (ADR-0004). An attribute is statement-backed by declaring a trait such as evidence.EvidenceBacked or using an Asserted<T> value-type wrapper. Only contested, source-reconciled facts carry this overhead. Canonical statement-backed attributes: geometry, capacity, as-built measurements. Canonical plain attributes: workflow status, comments, created_at.

Two things to keep distinct:

  • Auditability — every attribute is audited via the event log regardless of statement-backing. The event log records every Action and its outcome.
  • Multi-source conflict resolution — only statement-backed attributes participate. Statement-backing adds conflict resolution on top of the base audit guarantee.

The consistency model for statement-backed attributes — whether authority/conflict resolution runs inside the write transaction or in the async projection — is an open question gated on the spike in ADR-0003.

Value Types

A Value Type is the type-safety atom of the kernel. Every Attribute, Action parameter, Event payload member, and Statement value has one. Storage mapping, SDK codegen, validation, and agent tool-schema generation all derive from it.

The MVP set is approximately twelve types: Text, Timestamp, EntityRef, Confidence, Distance, LineString, Point, Polygon, Status, Money, Capacity, FiberCount.

The decision (ADR-0007): author all Value Types using the full manifest schema — so the on-disk shape is future-proof — but implement only validation, storage mapping, and SDK codegen in the MVP runtime. Deferred to later phases: versioning/upcasting (when a real v2 type emerges), aggregation-inference safety (SmartOps concern), per-type UI renderers.

The discipline is: shape for the vision, size the runtime for the proof. The manifest schema is designed once in full; only its interpreter grows over time. Adding deferred behavior later does not require re-authoring existing Value Type definitions.

See also

← Architecture