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. A draft MAY author a lesson (one capped imperative line); a lesson-bearing draft that survives GROUND + VERIFY stamps as an applicable, rollbackable ADD fact proposal instead of an advisory flag — still origin = llm, so applying it always takes a human review with a BECAUSE plus an explicit apply; 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.

PlanEdit

One field-level edit to a Workflow plan grain. from is a staleness check (it must equal what the live plan holds at path), which is what stops a proposal authored against a superseded plan from applying to a newer one — the role base_digest plays on super::recommendation::Proposal::Edit.

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

Enums

DraftProposal

What a DISCOVER draft proposes to change. Closed vocabulary: every variant maps onto an apply path that already records an inverse, and anything the model returns outside it leaves the draft advisory.

Constants

MAX_CODE_LEN

MAX_GUIDANCE_LEN

MAX_LESSON_LEN

An authored lesson is one imperative line — anything longer is a document, not a lesson, and a bound on what a single approved apply can put into every future prompt.

MAX_LLM_DRAFTS

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

MAX_OBJECT_LEN

MAX_PLAN_EDITS

MAX_QUERY_BODY_LEN

MAX_RELATION_LEN

Caps on the rest of the proposal vocabulary. Each one bounds what a single approved apply can put into every future run of the agent, so they are part of the trust floor rather than tuning knobs.

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