Confidence-driven knowledge graph promotion: EIDOS threshold gates KG entry creation

Start by reading the affected crates: terraphim_agent_evolution, terraphim_automata, terraphim_rolegraph, and terraphim_types, along with the related issues #597, #599, #600, and #601. Trace how insights and existing KG entries are represented before defining the promotion flow. Done means validated candidates can be gated against the stated criteria, written under docs/src/kg/promoted/, and made available through the automata rebuild path.

Summary

Knowledge graph entries should only be created when a learning or insight crosses a confidence threshold established by the EIDOS prediction-outcome loop. Confidence becomes the promotion gate between ephemeral memory (event store) and durable knowledge (Aho-Corasick KG).

Core Insight

Currently, KG entries are manually curated -- a human writes markdown files in docs/src/kg/, which get compiled into Aho-Corasick automata. This is high-quality but doesn't scale.

The proposed flow inverts the direction: learnings enter the system as low-confidence events (#599), get validated through predict-evaluate cycles (#601), and only when confidence crosses a threshold do they get promoted to KG entries that the Aho-Corasick engine indexes.

Event Capture (low confidence, ephemeral)
    |
    v
Event Store (#597) -- all events persisted, queryable
    |
    v
EIDOS Loop (#601) -- predict, observe, evaluate, distill
    |
    v  (confidence > promotion_threshold)
    |
KG Entry Created -- durable, indexed by Aho-Corasick automata
    |
    v
Automata Rebuilt -- new patterns available in search

Why This Matters

Self-Growing Knowledge Graph

The KG currently grows only when a human adds entries. With confidence-driven promotion, the KG grows autonomously as the system validates insights through real-world outcomes. The growth is quality-gated -- only validated knowledge enters the graph.

Deterministic-First Preserved

This preserves terraphim's deterministic-first philosophy. Once promoted, entries ARE the Aho-Corasick automata -- sub-millisecond, deterministic matching. The LLM/statistical reasoning is confined to the promotion decision, not the runtime lookup. The graph itself remains fast and deterministic.

Natural Pruning

Entries that stop being validated (confidence decays over time if not re-confirmed) could be demoted or flagged for review. This prevents KG bloat from stale patterns.

Promotion Criteria

An insight is promoted to a KG entry when ALL of:

1. Confidence > threshold (configurable, default 0.8) -- computed from EIDOS prediction accuracy
2. Validation count > minimum (configurable, default 5) -- must have been validated across multiple episodes
3. Recency check -- at least one validation in the last N days (prevents promoting stale patterns)
4. No contradiction -- no existing KG entry contradicts this insight (checked via Aho-Corasick match against existing patterns)
5. Quality gate pass -- Meta-Ralph 6-dimensional score (#600) above threshold on reliability + utility dimensions

KG Entry Format

Promoted entries are written as standard terraphim KG markdown:

# [Promoted Insight Title]

[Insight description derived from distillation]

synonyms:: [auto-extracted related terms]

## Source
- Promoted from EIDOS loop on [date]
- Confidence: [score]
- Validation count: [N]
- Prediction accuracy: [%]
- First observed: [date]

These files are placed in a designated directory (e.g., docs/src/kg/promoted/) and compiled into automata on the next rebuild.

Implementation Plan

1. Promotion Engine (new module in terraphim_agent_evolution)

pub struct PromotionCandidate {
    pub insight_id: Ulid,
    pub confidence: f64,
    pub validation_count: u32,
    pub last_validated: jiff::Timestamp,
    pub meta_ralph_scores: DimensionalScores,  // from #600
    pub suggested_kg_entry: KgEntry,
}

pub trait PromotionGate: Send + Sync {
    async fn evaluate(&self, candidate: PromotionCandidate) -> PromotionDecision;
    async fn promote(&self, candidate: PromotionCandidate) -> Result<KgEntryPath>;
}

2. KG Entry Generator (extend terraphim_automata or terraphim_rolegraph)

• Generate markdown KG entry from promoted insight
• Extract synonyms via Aho-Corasick match against existing thesaurus
• Place in docs/src/kg/promoted/ directory
• Trigger automata rebuild (incremental if possible)

3. Confidence Decay (in terraphim_agent_evolution)

• Entries not re-validated within configurable window get confidence decay
• Below demotion threshold -> flag for human review
• Human can confirm (reset confidence) or remove

4. Contradiction Detection (in terraphim_automata)

• Before promotion, match candidate against existing KG entries
• If existing entry contradicts candidate, flag for human resolution
• Prevents conflicting patterns in the automata

Affected Crates

• terraphim_agent_evolution (primary -- promotion engine + confidence decay)
• terraphim_automata (contradiction detection + incremental rebuild)
• terraphim_rolegraph (KG entry creation from promoted insights)
• terraphim_types (PromotionCandidate, PromotionDecision types)

Dependencies

• #597 Event sourcing (events are the raw material)
• #599 Enhanced learning capture (multi-hook events feed the pipeline)
• #600 Dimensional verdict scoring (Meta-Ralph scores gate promotion)
• #601 EIDOS episodic reasoning (confidence scores drive promotion threshold)

Estimated Effort

~1 day for promotion engine + KG entry generation. Contradiction detection and confidence decay are follow-ups.

Key Design Decision

The promotion threshold should be conservative by default (0.8 confidence, 5+ validations). It is better to miss a valid insight and let a human add it manually than to pollute the KG with unvalidated patterns. The KG's value comes from its precision -- every entry in the Aho-Corasick automata fires reliably. False positives in the KG are worse than false negatives.

Part of

Epic #595 (Ouroboros-inspired patterns -- extends the agent evolution theme)

Completes the pipeline:
Event Capture (#599) -> Event Store (#597) -> EIDOS (#601) -> Promotion (this issue) -> KG Entry -> Aho-Corasick Automata