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 present in the bundle (by bundle id, full hash, or an unambiguous hash prefix), 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. id is the bundle-local label (e1, e2, …) a draft may cite instead of the 64-hex hash: the engine resolves either back to the grain, so a citation is still checked against the bundle — it is just no longer a transcription test for the model.

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.

PlanEdgeDraft

One edge of a plan draft. cond is in the runtime’s frozen grammar (path == literal, path != literal, path exists, !path).

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.

PlanNodeDraft

One step of a plan draft: an identifier, the tool it calls, and what it does with it.

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_COND_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_PLAN_NODES

A plan has at most this many steps; a condition is one short line.

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_SKILL_NAME_LEN

A skill name is an identifier a person types at skill_view, not a title.

MAX_SKILL_STEPS

MAX_SKILL_STEP_LEN

A skill step is one instruction line; a skill has at most this many.

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