el_runtime/
ports.rs

1//! Port traits the Inference Runtime depends on (the collaborator contexts).
2
3use el_core::{Result, Token};
4use el_safety::{ChunkGuard, SafetySteerer};
5
6/// The inference engine adapter (`RuntimeAcl`). Implemented for real by Candle
7/// in the excluded adapter `el-engine-candle` (ADR-002).
8///
9/// Logits are integer milli-logits to keep the orchestrator deterministic and
10/// float-free; a real engine quantises its float logits at the ACL boundary.
11pub trait InferenceEngine {
12    /// Encode the (compressed) prompt; returns the resulting KV length.
13    fn prefill(&mut self, tokens: &[Token]) -> Result<u32>;
14    /// Produce next-token logits given the committed context.
15    fn next_logits(&mut self, committed: &[Token]) -> Vec<i32>;
16    /// The end-of-sequence token id.
17    fn eos_token(&self) -> Token;
18
19    /// Roll the engine's internal state back so its context is exactly the
20    /// prompt plus `keep_committed` generated tokens.
21    ///
22    /// The ADR-012 control loop truncates the session's committed output and KV
23    /// descriptors on a safety backtrack. A **stateful** engine (one holding a
24    /// real KV cache and position counters, e.g. a transformer) must mirror that
25    /// truncation here — otherwise it keeps serving logits from the abandoned
26    /// (unsafe) branch and never re-feeds the replacement tokens, so the rollback
27    /// is silently a no-op at the engine level.
28    ///
29    /// After `Ok(())`, the next [`next_logits`](Self::next_logits) call — passed a
30    /// `committed` slice of length `keep_committed` — must produce logits
31    /// consistent with that prefix. Returning `Err` makes the loop fail closed
32    /// rather than resume on an inconsistent cache.
33    ///
34    /// This method is **required, with no default**, deliberately: a default
35    /// no-op would let a stateful adapter that forgot to override silently resume
36    /// on a stale KV cache — a safety bug that fails *open*. Every engine must
37    /// make the choice explicit. A stateless engine whose `next_logits`
38    /// recomputes purely from `committed` implements it as `Ok(())`.
39    fn rollback(&mut self, keep_committed: u32) -> Result<()>;
40
41    /// Return the engine to its **pristine, pre-prefill** state so the same
42    /// loaded weights can serve a *new conversation* without being reloaded
43    /// (ADR-018). After `Ok(())`, the next [`prefill`](Self::prefill) must build a
44    /// KV cache from scratch as if the engine had just been constructed.
45    ///
46    /// This is distinct from [`rollback`](Self::rollback): `rollback(keep)` rewinds
47    /// *within* a generation to a safe prefix of length `keep` (ADR-012);
48    /// `reset_cache` discards the whole conversation. It is what lets a provider
49    /// hold one resident model and reuse it across turns instead of re-reading the
50    /// weights from disk every call.
51    ///
52    /// Like `rollback`, it is **required with no default**: a stateful adapter that
53    /// forgot to override would otherwise carry a stale cache into the next
54    /// conversation. A stateless engine whose `next_logits` recomputes purely from
55    /// `committed` implements it as `Ok(())`.
56    fn reset_cache(&mut self) -> Result<()>;
57}
58
59/// Prompt Compression port (LLMLingua-2 — context 2).
60pub trait PromptCompressor {
61    fn compress(&self, tokens: &[Token]) -> Vec<Token>;
62}
63
64/// Grammar Constraint port (llguidance — context 4). Returns a per-token allow
65/// mask of length `vocab`; `true` = legal this step.
66pub trait GrammarMasker {
67    fn mask(&self, recent: &[Token], vocab: usize) -> Vec<bool>;
68}
69
70/// Opt-in LAN relay (ADR-004 HybridMode). Implementations MUST stay on the local
71/// network — there is no cloud variant.
72pub trait HybridRelay {
73    fn consult(&self, query_tokens: &[Token]) -> Vec<Token>;
74}
75
76/// The collaborator ports bound to a session. `relay` is `None` by default —
77/// air-gapped.
78pub struct Ports {
79    pub compressor: Box<dyn PromptCompressor>,
80    pub grammar: Box<dyn GrammarMasker>,
81    pub safety: Box<dyn SafetySteerer>,
82    /// Optional chunk guard for the checkpointed-rollback control loop
83    /// (ADR-012). `None` runs the plain single-pass decode.
84    pub guard: Option<Box<dyn ChunkGuard>>,
85    /// Optional **ingress / prompt-risk triage** (ADR-013): scores the prompt
86    /// before generation. Reuses the [`ChunkGuard`] contract — it scores a token
87    /// window for risk — applied to the prompt rather than the output. `None`
88    /// runs no ingress check.
89    pub ingress: Option<Box<dyn ChunkGuard>>,
90    pub relay: Option<Box<dyn HybridRelay>>,
91}
92
93impl Ports {
94    /// Defaults: identity compression, all-tokens-allowed grammar, no safety
95    /// steering, no guard, no ingress, no relay (air-gapped).
96    pub fn permissive() -> Self {
97        Self {
98            compressor: Box::new(super::defaults::IdentityCompressor),
99            grammar: Box::new(super::defaults::AllowAllMasker),
100            safety: Box::new(el_safety::NoSafety),
101            guard: None,
102            ingress: None,
103            relay: None,
104        }
105    }
106}
el_runtime/ports.rs

el_runtime/
ports.rs
