> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0005: Temporal fact and patch lifecycle

> Preserve auditable memory evolution through temporal facts and gated patch promotion.

<Info>**Status:** Accepted **Date:** 2026-02-06 **Deciders:** Reflections Maintainers</Info>

## 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.

## Related ADRs

* [ADR-0003: Two-plane system architecture](/decisions/adr-0003)
* [ADR-0010: Ingestion orchestration, idempotency, and recovery](/decisions/adr-0010)
* [ADR-0007: Retrieval pipeline design](/decisions/adr-0007)