# L3 — Grounding: make Kai say TRUE things, fluently

**Goal:** the grammar-first decoder generates from a **retrieved fact's meaning**, not just the
prompt's words — so Kai is *correct*, not only fluent. Salad is fixed; this is the next tier.

---

## What already exists (leverage, don't rebuild)

- **Retrieval:** `Universe::predictive_query` / `predictive_query_by_source` returns ranked
  `QueryHit`s (each has `text`, a `SparseVec`, `score`, `source`, `keywords`). It can be
  filtered to `source == "truth-anchor"` — i.e. retrieve **facts**, not chatter.
- **A knowledge base — but a narrow one.** `[internal module]` = **52 curated facts**,
  `[internal module]` = 108 truth-anchor claims. **Honest catch:** they are almost all about
  **Kai himself** ("KAI is not an LLM", "KAI is a Rust system", "Universe is generative memory").
  A grep for cat / vowel / two-plus-two / four = **0**. So today he only *knows* himself.
- **The fluent decoder:** `StatLexicon::generate_grammar_first(meaning, seed, params, mw, gw, info)`
  — transcripts nominate, meaning steers. This is what fixed the salad.
- **A first grounding attempt:** `try_grounded_generation` (behind `[config flag]`) re-orders a
  retrieved cell's *words* with `word_calculus::assemble`. It reshuffles the fact rather than
  *generating from* it — keep as a fallback, not the target.

---

## The core mechanism (the real change)

Wire **retrieval → the grammar-first decoder** so the *meaning spine is a fact*:

1. **Retrieve.** For the prompt, run `predictive_query`; prefer `truth-anchor` / high-score hits.
2. **Ground the meaning.** Build the decoder's `meaning` vector from the retrieved fact's text
   (`encode_sentence(fact)`), optionally blended with the prompt. Meaning = the fact.
3. **Seed + steer from the fact.** Open on the fact's key noun; add a **fact-cosine term** to the
   candidate scoring so the chain expresses the fact instead of drifting into corpus filler
   ("…anniversary gift…"). This is the fix for the mid-sentence drift you saw.
4. **Confidence gate (honesty).**
   - Strong fact (score ≥ threshold) → generate grounded in it → fluent **and** correct.
   - Weak / no fact → fall back to today's ungrounded grammar-first with a hedge
     ("From what I understand…"), or say he doesn't know. **Never state a guess as fact.**

Plugs into `voice.rs generate_raw_thought`, in the grammar-first block, behind a flag
(default OFF, byte-identical when off).

---

## Two tracks — and why data is half the battle

**Track A — code (wire retrieval → generator).** Buildable now. With the 52 self-facts it will
**immediately** make him answer self-questions correctly *and* freshly — "are you an LLM?",
"what are you?", "what is the Universe?" become grounded fluent sentences, not chatter. That's a
real, demonstrable win on day one.

**Track B — data (grow the truth store).** This is the true ceiling. Grounding can only make him
correct on topics that **exist** in the store. For "what is a cat" to be right, a cat fact must
be there. Path: curate world facts and `--truth-import` them (the pipeline exists). This is
DATA work, not decoder work — and it's what turns grounded-Kai from "knows himself" into
"knows things."

---

## Phases

- **L3a — retrieval→meaning wiring.** Feed the top fact into `generate_grammar_first` as meaning +
  seed. Flag-gated. *Measure:* does grounded output contain the fact's content words?
- **L3b — fact-steering.** Add the fact-cosine term to candidate scoring so the chain stays on the
  fact. *Measure:* topicality / factual-word retention vs L3a.
- **L3c — confidence gate + honesty.** Strong fact → state it; weak → hedge or defer. *Measure:*
  zero confident-wrong answers on prompts with no fact.
- **L3d — grow the KB.** Curate + import world facts. *Measure:* correct answers to a held-out set
  of general questions.

## Measurement (extend `--gen-probe`)

Add a grounded A/B: for prompts that DO have a truth-claim (start with the self-questions), print
ungrounded vs grounded output + whether the fact's key terms survived. Same honest, deterministic
harness we used to prove the salad fix.

## Honest bottom line

The **mechanism** is a clean, contained code change and it will work — I can prove it on his
self-knowledge immediately. Broad correctness is a **data** problem (52 facts, all about himself).
So L3 is ~40% decoder wiring, ~60% growing the truth store. Anyone who tells you the decoder alone
makes him "know things" is selling hopium.