Skip to content

The tritemporal model

Concept 2 of 8

Telha stamps three clocks on every fact. This is the single idea that lets you ask what was true, as we knew it, on any date, and get an answer that is still correct after the fact has been corrected, superseded, or deleted.

Normative spec

This concept is defined by version-record-model and the core-engine/src/model/ and core-engine/src/temporal/ implementations. The deep engineering treatment (the winner rule, storage layout, and write path) is in Architecture › The version record model.

The three clocks

Every NodeVersion and EdgeVersion carries three time fields:

Clock Field Question it answers Business framing
Valid time valid_time: Interval When was this true in the world? when it was true
Transaction time tx_time: Interval When did Telha record or believe it? when we learned it
Source-record time source_record_time: Option<u64> What date does the source document itself assert? the date on the page

Valid time and transaction time are intervals (half-open, [start, end)). Source-record time is a single instant that rides along as provenance, pinning each fact to the date its source asserts so that citations point to the document as written.

Tritemporal, not bitemporal

Telha is tritemporal: three clocks are stamped on every version. The word bitemporal appears only for the narrow winner rule (the truth table that selects the in-force version over the valid × transaction plane). The query API exposes two addressable coordinates, atValidTime and atTxTime; source-record time is carried as provenance, not queried directly.

Why two axes are not enough on their own

Consider a supplier-risk fact that gets corrected:

sequenceDiagram
    autonumber
    participant W as World (valid time)
    participant T as Telha (transaction time)
    Note over W: May 1, the risk owner is Michael
    Note over T: Feb 3, Telha records "owner = Sarah"<br/>(from an out-of-date org chart)
    Note over T: Apr 9, correction arrives:<br/>"owner was Michael as of May 1"

Now ask the same question, "who owned this risk on May 1?", two ways:

{"find": "RISK", "atValidTime": "2026-05-01T00:00:00Z"}

Answer: Michael. With no atTxTime, Telha uses the latest belief, and the April 9 correction is in force.

{"find": "RISK",
 "atValidTime": "2026-05-01T00:00:00Z",
 "atTxTime":    "2026-02-03T00:00:00Z"}

Answer: Sarah. Pinning transaction time to before the correction reconstructs exactly what Telha believed at that moment, the value any report run on Feb 3 would have used.

A single "last write wins" store cannot answer the second question at all: the old belief is gone. Telha keeps every version, so "what did we believe about our exposure in March, before the amendment arrived" is answerable, forever.

History is append-only

Corrections and deletions never destroy data:

  • A correction writes a new version. The superseded version stays reconstructable at its original transaction time.
  • A deletion writes a tombstone version (valid time opens at the delete instant). Past snapshots stay whole; the entity simply reads as absent from the tombstone forward.
Version Valid time Transaction time State
v1 [Jan 1, Jun 30) [Feb 3, Apr 9) Superseded
v2 [Jan 1, Jun 30) [Apr 9, ∞) Current
v3 [Aug 1, ∞) [Aug 1, ∞) Tombstoned

Because writes are append-only, the winning version for any (validTime, txTime) pair is deterministic and stable: it never changes retroactively when new data arrives.

The winner rule (in one paragraph)

Among all versions of an entity whose valid interval and transaction interval both contain the queried (vT, tT), the winner is the one with the highest tx_time.start (the most recently recorded belief that was in force at tT). If that winning version is a tombstone, the entity reads as absent. This is the "bitemporal truth table," and it is proved against a brute-force reference implementation in the engine's tests.

Try it

  • atValidTime alone → what is true at that world-date, as best we know now.
  • atTxTime alone → everything we believed as of that recording-date.
  • Both → what we believed at recording-date about world-date, the exact state any report produced at atTxTime would have used.
  • Neither → current state.

Where this shows up in the product

  • Queries: atValidTime / atTxTime on /v1/query and /v1/snapshot.
  • Diffs: /v1/compare computes added / removed / modified between any two temporal coordinates.
  • Vectors: semantic search is partitioned by validity, so time-travel applies to similarity too.
  • Answers: a generated answer that depended on a still-pending fact carries an explicit caveat until the fact is confirmed.