Module llm 

Optional LLM enrichment (proposal §9).

The engine’s deterministic output stays a pure function of (store, params, now). This layer is strictly additive: with a backend attached the pipeline gains two optional stages —

ANALYZE (deterministic) → DISCOVER (LLM) → ENRICH (LLM) → VALIDATE+DEDUP → STORE

and with no backend those stages are the identity function, so the no-LLM path is byte-for-byte the deterministic path. The LLM can only:

• DISCOVER: propose new draft recommendations, which enter through the ordinary candidate/dedup/store path stamped origin = llm — so they can never auto-apply and never target prompt/host surfaces; and
• ENRICH: add a whitelisted guidance note to a deterministic recommendation. The engine-templated summary is always kept; the model never rewrites it.

Trust floor (enforced by the engine, not the backend): responses are parsed to a fixed schema (unknown fields dropped, strings capped), DISCOVER drafts must cite evidence hashes present in the bundle, instructions never interleave with evidence, and a failed/timed-out/garbled call drops the LLM contribution for the run rather than failing it.

CommandLlm mirrors the shipped CommandEmbed: whitespace-split argv (no shell), one process per call, a JSON request on stdin and a JSON response on stdout, and a construction-time probe that fails loud.

Structs

CommandLlm

A subprocess LLM backend. One process per call; argv is whitespace-split with no shell (identical rules to CommandEmbed).

DiscoverResponse

The DISCOVER response.

EnrichNote

EnrichResponse

The ENRICH response: guidance keyed by target_ref of a deterministic rec.

EvidenceItem

One evidence grain, provenance-tagged.

FindingBrief

One deterministic finding, handed to DISCOVER as context (never as an instruction — see LlmRequest).

GroundItem

GroundRequest

GROUND request: for each candidate draft, does its cited evidence actually entail the claim? Decompose-then-entail is asked of the model here; a stronger deployment can swap a dedicated entailment checker behind the same shape. Kept a separate op/call from DISCOVER (proposer ≠ grounder).

GroundResponse

GroundResult

LlmDraft

One DISCOVER draft as returned by the model. Unknown fields are dropped by serde; the engine further validates (cite-check, caps, target class, grounding, and independent verification before it is ever stored).

LlmRequest

The request envelope. op selects the stage; instructions is a fixed engine string kept in its own field so it never interleaves with evidence.

VerifyItem

VerifyRequest

VERIFY request: an independent adversarial pass (a separate call from the proposer — the anti-Goodhart rule) that tries to refute each grounded draft on novelty / reality / out-of-context grounds and returns keep/kill + a calibrated confidence. Deterministic findings are passed as context so the verifier can reject drafts that merely restate them.

VerifyResponse

VerifyResult

Constants

MAX_GUIDANCE_LEN

MAX_LLM_DRAFTS

Caps that bound what a single LLM contribution can inject (defense in depth; the engine enforces them after parsing).

MAX_SUMMARY_LEN

Traits

LlmBackend

A backend that answers one JSON request with one JSON response. Object-safe so the engine can hold a Box<dyn LlmBackend>.

Functions

cap

Truncate to a char cap without splitting a UTF-8 boundary.

parse_discover

Parse a DISCOVER response, dropping anything malformed. Never errors on model garbage — a bad response yields no drafts.

parse_enrich

Parse an ENRICH response, dropping anything malformed.

parse_ground

Parse a GROUND response; garbage → no results (⇒ every draft is treated as ungrounded and dropped, the safe default).

parse_verify

Parse a VERIFY response; garbage → no results (⇒ every draft is dropped).