Skip to content

Glossary

Reference

Precise, one-paragraph definitions of the terms Telha's documentation and API surfaces use. Alphabetized; each links to a deeper page where one exists.

AAD

Additional Authenticated Data: a value bound into an authenticated-encryption ciphertext without being encrypted itself, so decryption fails if the value is wrong even though it was never secret. Telha's field-level envelope encryption binds the record's lexicographically smallest label as AAD, so a ciphertext envelope transplanted onto a different label fails authentication (it cannot be silently reused across label sets). See Architecture › Field encryption.

API key

The tenant-facing credential for REST: a plaintext string (tk_...) shown once at telha api-key create and stored at rest only as a hash in {data_dir}/api_keys.json. An API key is scoped to one (tenant, organization) pair and is sent as the x-api-key header. It may optionally bind a PERSON and rights so it can answer clarifications; without that binding it cannot answer at all. API keys never open the /admin surface, which is gated by operator-minted tokens instead. See CLI reference › api-key create.

Bitemporal winner rule

The selection rule that picks the single "in force" version of an entity for a queried (validTime, txTime) coordinate: among all versions whose valid interval and transaction interval both contain the coordinate, the winner is the one with the highest tx_time.start (the most recently recorded belief that was in force at that transaction time). If the winning version is a tombstone, the entity reads as absent. See Concepts › The tritemporal model and Architecture › The version record model.

Budget

The token ceiling B a memory-plan is packed against. The default comes from planner.default_budget (6,000) unless the request supplies one, and the effective budget is further bounded by min(B, floor(model_ctx × 0.5)) when the LLM provider reports a context window. Spans are greedily packed by weight-per-token density until the budget is exhausted; spans that no longer fit are skipped, and unpackable oversized spans are recorded in stats rather than silently dropped. See Configuration keys › [planner] and Architecture › Memory planner.

Cascade

The atomic, strictly append-only write-set that tombstones a node or edge: it appends the tombstone version itself plus every index and adjacency entry needed to keep past snapshots correct, and it never deletes historical rows. The cascade exists to prevent two failure modes: "forward ghosts" (dead structure still traversable after a delete) and "backward ghosts" (deleting adjacency or index rows blinds queries at coordinates before the tombstone, erasing history that genuinely existed). See Architecture › Tombstone cascade.

Claim

An atomic, declarative statement extracted from a generated draft by the claim-verification decomposition step (an LLM call constrained to JSON output: {claim_text, draft_span, cited_markers[]}). Non-factual text (hedges, transitions, questions) is classed non_claim and skipped. Every claim is scored against the evidence plan's spans to produce a verdict. See Architecture › Claim verification.

Clarification

A routed, RBAC-gated question Telha asks a human when ingestion detects temporal ambiguity in a fact (an undated scan, conflicting amendment dates, "effective next quarter"). Clarifications are governed evidence capture, not chat: answers are recorded append-only as response records, and a fact is corrected only once the binding policy (including quorum for high-stakes facts) is satisfied. Answering is a write: an editor-or-above response is binding-capable, while a viewer's response is an attestation requiring confirmation. See CLI reference › clarify and the operator handbook.

Column family

A named, independently-tuned key space within RocksDB (Telha's storage engine); each column family holds one logical record type (e.g. node_versions, edge_versions, bitmap_index, vectors). Every key in every column family is constructed exclusively through the KeyCodec/TenantScope/ScanRange API, which is what makes tenant isolation true by construction rather than convention. See Architecture › Storage engine & key layout.

Compare

The temporal delta operation (POST /v1/compare) that computes added, removed, and modified nodes and edges between two full bitemporal coordinates (a baseline and a comparison, each {validTime, txTime}). Classification rules: present at the comparison but not the baseline is added; the inverse is removed (with a reason distinguishing tombstone from validity-lapse); present at both with the same version is unchanged (not emitted); present at both with different versions is modified, carrying a property-level diff. See Architecture › Snapshot & compare.

Confidence

The per-fact reliability score used to rank and weight evidence. Two contributors combine: sim(n) (semantic similarity from the vector stage) and decay(n) (graph-distance decay); the final score S(n) = sim(n)^α · decay(n)^(1−α) fuses them under a tunable balance exponent α (decay.fusion_alpha, default 0.6). S(n) is the evidence weight the memory planner consumes unchanged. See Configuration keys › [decay] and Architecture › Confidence decay.

Cursor

An opaque, server-signed continuation token for paging query results: base64(msgpack{v, scope_hash, last_key, plan_hash}), HMAC-signed with a server key. Resuming a cursor validates scope_hash (so a cursor cannot be replayed against another tenant) and plan_hash (the query must be identical to the one that issued the cursor, except for the cursor itself). Cursors do not compose with vector-ranked queries. See Developers › Query language.

Decay

The multiplicative per-hop attenuation applied as graph traversal expands outward from a starting node: each hop multiplies by a per-edge-type weight (decay.weights.<EDGE_TYPE>, falling back to decay.default_weight = 0.7), assigned along the shortest path (guaranteed by BFS). A floor (decay.floor, default 0.05) prunes paths below negligible weight rather than continuing to expand them. Decay is one of the two inputs fused into confidence. See Architecture › Confidence decay.

Edge version

The versioned record of a relationship between two nodes, analogous to a node version but carrying edge_logical_id, from, and to endpoints in addition to the same tritemporal fields (valid_time, tx_time), properties, and provenance. Stored in the edge_versions column family. See Architecture › The version record model.

Fusion (alpha)

The balance exponent α in the score-fusion formula S(n) = sim(n)^α · decay(n)^(1−α), ranging [0, 1] with a default of 0.6 (decay.fusion_alpha). It is the one fusion parameter with a per-query override ("vector": {"alpha": 0.4}), always bounded to [0, 1]. The same geometric-fusion form (with its own β) also underlies claim-verification's claim↔span matching. See Configuration keys › [decay].

KEK / DEK

Key-Encrypting Key and Data-Encrypting Key: the two tiers of Telha's app-layer envelope encryption for classified fields. Each tenant has a DEK that actually encrypts field bytes (XChaCha20-Poly1305); the DEK itself is wrapped by a KEK held outside the tenant's data (v1 ships an env-provided KEK via FIELD_CRYPTO_KEK, with a KmsProvider interface for pointing at a real KMS later without a code change). Rotating a DEK re-encrypts forward (new versions under a new key id) while historical versions stay readable under their original key until an explicit destruction event; the KEK never lives on the core host. See the operator handbook.

MCP

Model Context Protocol: the integrated server built into the telha binary (alongside REST and gRPC) that exposes Telha's capabilities as tools for a language model acting on a human's behalf. An MCP session authenticates with the same signed-token scheme as gRPC (audience mcp) and binds one tenant scope at session initialize; tools accept no tenant parameters. Results are shape-capped (rows and per-field text) so a tool call cannot blow a model's context window. See Developers › MCP tools.

Node version

The versioned record of a graph entity: logical_id, sorted/deduped labels, properties, the valid_time and tx_time intervals, a tombstone flag, and mandatory provenance. Stored in the node_versions column family, serialized with a value-version-prefixed MessagePack encoding so the format can evolve additively. See Architecture › The version record model.

Plan

The output of the memory planner's two phases: Phase A recalls candidate evidence (structured query results, semantic search, 1-2 hop graph expansion) and explodes it to provenance spans; Phase B greedily packs those spans by weight-per-token density under a budget, with a hard per-source diversity cap and same-source near-duplicate suppression. A plan's canonical serialization is deterministic (fixed float encoding and evaluation order) so its plan_hash is reproducible across platforms. See Architecture › Memory planner.

Provenance

The mandatory struct on every node and edge version recording where it came from: an origin (Api | Ingestion{source_id, job_id} | System | Cascade), an optional actor, and an optional request_id. Provenance is what lets any fact be traced back to the exact ingestion event (and, via spans, the exact source bytes) that produced it. See Architecture › The version record model and Architecture › Ingestion & provenance.

Quorum

The multi-confirmation requirement that gates binding a critical-severity clarification: critical clarifications must not bind on a single response unless the tenant's steward-override policy explicitly permits it. The default policy (clarify.quorum) requires 2 matching binding-capable confirmations from roles in required_roles (default ["editor"]); a steward may still bind single-handedly via an explicit override when allow_steward_override is true. Quorum satisfaction is itself recorded as evidence. See Configuration keys › [clarify].

ScanRange

The sole API for obtaining RocksDB iterator bounds: every constructor derives a [prefix, successor(prefix)) range from a TenantScope plus typed components, so no code path can construct a scan that crosses a tenant's key prefix. There is no public constructor accepting raw start/end bytes; enforcement is layered (restricted visibility, a CI grep-gate, property tests, and a fuzz target on the decoder). See Architecture › Storage engine & key layout.

Scope (tenant / organization)

The mandatory (tenant_id, organization_id) pair that prefixes every key Telha writes and bounds every scan. Scope is never taken from a request body: REST derives it from the API key, gRPC and MCP derive it from a signed internal token, and the CLI takes it as explicit --tenant/--org flags. A dedicated nil-tenant "system" namespace exists for cross-tenant maintenance jobs (the job-queue reaper) and is unreachable from any external request path. See Architecture › Storage engine & key layout.

Snapshot

A query resolved at a single, explicit bitemporal coordinate (atValidTime and/or atTxTime) rather than at "now." POST /v1/snapshot takes the same grammar as /v1/query and returns the winning versions as of that coordinate, per the bitemporal winner rule. Two snapshots are the inputs to compare. See Concepts › The tritemporal model.

Source version

The record of one ingestion event for a given source identity (tenant, source_id): it carries a content_hash (BLAKE3 of the raw bytes), the original filename or URL, the format, and a reference to the canonical extracted text. Re-ingesting identical bytes for the same source_id is a no-op (content-hash dedup); different bytes for the same source_id create a new source version. Every node produced by ingestion carries provenance.spans pointing back to specific source versions. See Architecture › Ingestion & provenance.

Source-record time

One of Telha's three clocks: the date the source document itself asserts, carried as a single instant (not an interval) alongside provenance. It pins a citation to the document as written, distinct from when Telha recorded the fact (transaction time) or when the fact was true in the world (valid time). It rides along as provenance rather than being a directly queryable coordinate. See Concepts › The tritemporal model.

Span

A half-open byte range [start, end) into the canonical extracted text of one specific source version, never into raw file bytes and never token-model-dependent. Spans are the evidence unit claim verification matches against, and they carry a kind (e.g. paragraph, heading, cell, code) that weights their planner priority. See Architecture › Ingestion & provenance.

Steward

The workspace-level fallback authority for clarifications: when no better-ranked candidate (source-span author, person named in the fact, source-record owner) passes the read-authorization gate, the steward receives a redacted question instead. Stewards also work the review queue (telha clarify queue) for conflicted, expired, or dead-lettered clarifications and can bind an explicit override on a conflicted one (telha clarify review). See CLI reference › clarify review.

Tenant token

A signed internal token (HMAC-SHA256 over tenant id, organization id, issued-at, and audience) that carries tenant identity across the gRPC boundary between the app layer and the core engine. It is the sole mechanism a gRPC interceptor uses to construct a TenantScope; a raw tenant-id header is deliberately never trusted. Distinct token audiences (worker, mcp, clarify, admin, connector) keep each caller's capabilities disjoint by construction. See CLI reference › keys and tokens.

Tombstone

A version marked tombstone: true whose valid-time interval opens at the delete instant. Tombstones are ordinary versions (never a special key form): past snapshots taken before the tombstone stay whole, and the entity simply reads as absent from the tombstone's valid time forward. Deleting an entity is therefore an append (a new tombstone version plus its cascade), never a removal of history. See Concepts › The tritemporal model.

Trace

The persisted, immutable assembly record of one generation or verification call: the request summary, the evidence plan, the prompt hash, per-claim verdicts, and span links back to source bytes. GET /v1/trace/<traceId> returns it; a trace not found in the caller's tenant scope is 404 NOT_FOUND. See Developers › Generation & traces.

Transaction time

One of Telha's three clocks: the interval during which Telha recorded or believed a fact, distinct from when the fact was true in the world (valid time). Pinning atTxTime on a query reconstructs exactly what Telha believed at that moment, including beliefs later corrected. See Concepts › The tritemporal model.

Tritemporal

Telha's model of stamping three clocks (valid time, transaction time, source-record time) on every version, as opposed to "bitemporal," which in Telha's usage refers narrowly to the two-axis winner rule truth table over the valid × transaction plane. The query API exposes two addressable coordinates (atValidTime, atTxTime); source-record time travels as provenance rather than as a query parameter. See Concepts › The tritemporal model.

Valid time

One of Telha's three clocks: the interval during which a fact was true in the world, independent of when Telha learned it (transaction time). Pinning atValidTime alone answers "what is true at that world-date, as best we know now." See Concepts › The tritemporal model.

Verdict (supported / partial / unsupported)

The three-band outcome of scoring a claim against its best-matching evidence span: supported (score ≥ verify.bands.supported, default 0.75), partial (in [verify.bands.partial, supported), default floor 0.50), or unsupported (below that). A claim asserting a number with no matching normalized numeric in any candidate span is capped at 0.2 regardless of lexical/semantic similarity (the "numeric gate"): figures require figure evidence. The unsupported-claim policy (verify.policy) then either flags (annotates, default) or redacts the claim. See Configuration keys › [verify] and Architecture › Claim verification.

Worker token

A short-lived signed token (audience worker) minted by telha api-key worker-token, accepted only by WorkerService. It authenticates stateless Python format workers (docling, tabular, web, email, code) polling for and leasing ingestion jobs over gRPC; it cannot lease clarify: or sync: jobs, which have their own dedicated audiences. See CLI reference › api-key worker-token.