Skip to main content
Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers

​
Context

The system must support evolving truth without destructive overwrites, while preventing unvetted extracted facts from immediately becoming active user-visible truth.

​
Decision

Use an append-oriented temporal model for facts and a patch lifecycle gate:
  • Facts have valid_from, valid_to, and supersedes_fact_id fields to model temporal validity and lineage.
  • Fact state is explicit: active, candidate, rejected.
  • New learned facts are inserted as candidate and linked to a patch_batch.
  • Patch batches move through status lifecycle before application; only approved/applied paths activate promoted knowledge.

​
Alternatives considered

​
Alternative 1: In-place updates to a single current fact row

Pros:
  • Simple CRUD operations.
  • Lower row count.
Cons:
  • Loses historical provenance.
  • Harder rollback/audit for wrong extractions.

​
Alternative 2: Event-sourced log without current-state table semantics

Pros:
  • Complete immutable history.
Cons:
  • Requires expensive projection logic for hot-path reads.
  • More complexity than needed for current product stage.

​
Alternative 3: Immediate activation of extracted facts

Pros:
  • Fastest propagation from ingestion to retrieval.
Cons:
  • High risk of low-quality or hallucinated facts entering production truth.
  • Violates evaluation gate safety model.

​
Consequences

Benefits:
  • Preserves historical auditability of fact evolution.
  • Supports explicit promotion/rejection workflows.
  • Enables robust safety gating before truth-table updates.
Costs:
  • More lifecycle states and query conditions to manage.
  • Extra background orchestration complexity.

​
Implementation notes

  • Fact and patch enums/tables are defined in the foundational migration.
  • Candidate insertion and active retrieval behavior are implemented in the DB queries layer.
  • Patch state transitions and apply logic are orchestrated in the worker ingestion pipeline.