Core concepts · 30 / 42

Locked facts

Understand the repository substrate for evidence-backed, versioned facts and the boundary between database procedures and public product behavior.

A locked fact is an evidence-backed value addressed by tenant, entity, and fact key. The repository substrate preserves versions through transaction-time supersession instead of silently replacing the earlier recorded version. There is no direct public facts REST API in the frozen caller-memory surface.

Table shape

Column	Purpose
`ref_id`	Version identifier.
`tenant_id`	Tenant scope and RLS boundary.
`entity_id`	Person, account, repository, or other subject.
`fact_key`	Stable name of the fact.
`fact_value`	JSON value.
`evidence_ref_id`	Required reference to source evidence.
`valid_range`	When the value applies in the world.
`tx_range`	When this recorded version was current in the system.
`supersedes_ref_id`	Link to the prior version.
`created_at`	When the row was written.
`space_id`	Context Space placement; null means unplaced.
`fact_key_raw`	The key spelling the writer supplied, kept beside the normalized `fact_key`.
`validity_upper_prior`	The valid-time upper bound before an evolution narrowed it, for the two-clock as-of read.

A GiST exclusion prevents overlapping transaction-time versions for the same tenant/entity/key tuple.

Assertion, evolution, and correction

The migration defines four database procedures:

assert_fact inserts a first fact with evidence and a valid-time range.
evolve_fact closes the prior transaction-time range and inserts a successor with a caller-supplied valid range.
correct_fact closes the prior transaction-time range and inserts a marked correction that retains the earlier valid range.
get_fact_as_of has a four-argument form that selects the version believed at a requested timestamp (transaction time), and a five-argument form that takes both a valid-time timestamp and a believed-at timestamp.

Those functions are database primitives. They do not create /v1/facts, lock, resolve, or audit-chain endpoints.

“Locked” does not mean immutable forever

A locked fact can be superseded by an evidence-backed evolution or correction. Retention, tenant deletion, and legal erasure requirements also still apply. The useful invariant is that ordinary change creates a new version rather than silently rewriting the earlier recorded version.

Serving boundary

The design direction is to make relevant facts available to governed context and validation paths. That serving behavior is not established merely because migrations exist. A production claim requires evidence that the deployed path selected the correct entity/key version, enforced tenant isolation, attached the expected evidence and policy, and exposed the result to the customer.

Read Evidence references for provenance and Bi-temporal validity for valid-time versus transaction-time questions.