B5: D2+D3 ticket emission + Grammar Triangle bridge

claude · claude · commit c10f849b3fea · 2026-04-29T04:54:34.000Z
diff --git a/crates/deepnsm/src/parser.rs b/crates/deepnsm/src/parser.rs
@@ -440,6 +440,167 @@ pub fn parse_with_secondary(tokens: &[Token]) -> SentenceStructure {
     result
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// Coverage-branch hook for D2 FailureTicket emission.
+//
+// Wraps the existing free-function parser in a thin newtype that owns the
+// coverage threshold (default 0.85; configurable later from D7
+// `GrammarStyleConfig`). When a parse falls below threshold, the hook
+// hands the partial off to `ticket_emit::emit_ticket` so the LLM-tail
+// router can route the failure-mode itself as the inference signal.
+//
+// `Parser::parse` is preserved verbatim against the free `parse()` so no
+// existing call sites break.
+// ────────────────────────────────────────────────────────────────────────
+
+/// Default coverage threshold below which a parse triggers a FailureTicket.
+/// Mirrors `lance_graph_contract::grammar::LOCAL_COVERAGE_THRESHOLD` (0.9)
+/// minus a small slack so DeepNSM's looser FSM gets a chance.
+pub const DEFAULT_COVERAGE_THRESHOLD: f32 = 0.85;
+
+/// A parse outcome plus the metrics needed to decide whether it should
+/// escalate to the LLM router.
+#[derive(Clone, Debug)]
+pub struct ParseResult {
+    /// Token-derived semantic structure.
+    pub structure: SentenceStructure,
+    /// Coverage ∈ [0, 1]: classified-tokens / total-tokens.
+    pub coverage: f32,
+    /// Tokens the FSM successfully classified (rank-encoded).
+    pub resolved_tokens: Vec<u16>,
+    /// Tokens the FSM could not place (rank-encoded; OOV / unknown PoS).
+    pub unresolved_tokens: Vec<u16>,
+    /// NSM-prime count found in the resolved set. Drives Abduction routing.
+    pub primes_found: u8,
+    /// Distance vs. the SPO's expected qualia footprint (0.0 = identical).
+    /// Filled by `triangle_bridge::compute_classification_distance` once
+    /// the Triangle is wired; stays 0.0 in the bare-DeepNSM path.
+    pub classification_distance: f32,
+}
+
+/// Newtype around the FSM parser. Owns the coverage threshold so the
+/// LLM-tail policy is colocated with the parse decision instead of
+/// scattered across call sites.
+#[derive(Clone, Debug)]
+pub struct Parser {
+    coverage_threshold: f32,
+}
+
+impl Default for Parser {
+    fn default() -> Self {
+        Self {
+            coverage_threshold: DEFAULT_COVERAGE_THRESHOLD,
+        }
+    }
+}
+
+impl Parser {
+    /// Construct with the default 0.85 threshold.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Override the coverage threshold (D7 `GrammarStyleConfig` will feed
+    /// this once style-aware routing lands).
+    pub fn with_threshold(mut self, threshold: f32) -> Self {
+        self.coverage_threshold = threshold.clamp(0.0, 1.0);
+        self
+    }
+
+    /// Current coverage threshold ∈ [0, 1].
+    pub fn coverage_threshold(&self) -> f32 {
+        self.coverage_threshold
+    }
+
+    /// Run the FSM and return the structure unchanged (preserves the
+    /// existing public `parse()` shape for callers that don't need
+    /// coverage metrics).
+    pub fn parse(&self, tokens: &[crate::vocabulary::Token]) -> SentenceStructure {
+        parse(tokens)
+    }
+
+    /// Coverage-aware parse: returns the structure plus the metrics
+    /// `maybe_emit_ticket` needs.
+    pub fn parse_with_coverage(&self, tokens: &[crate::vocabulary::Token]) -> ParseResult {
+        let structure = parse(tokens);
+
+        let mut resolved = Vec::new();
+        let mut unresolved = Vec::new();
+        let mut primes = 0u8;
+        for t in tokens {
+            match t.rank {
+                Some(r) => {
+                    resolved.push(r);
+                    // NSM primes occupy fixed low ranks in the COCA
+                    // vocabulary (62/63 of them per lib.rs header).
+                    // Treat r < 64 as a primes-found heuristic.
+                    if r < 64 {
+                        primes = primes.saturating_add(1);
+                    }
+                }
+                None => unresolved.push(0u16),
+            }
+        }
+
+        let total = (resolved.len() + unresolved.len()) as f32;
+        let coverage = if total == 0.0 {
+            0.0
+        } else {
+            resolved.len() as f32 / total
+        };
+
+        ParseResult {
+            structure,
+            coverage,
+            resolved_tokens: resolved,
+            unresolved_tokens: unresolved,
+            primes_found: primes,
+            classification_distance: 0.0,
+        }
+    }
+
+    /// Whether the result fell below the configured threshold.
+    pub fn coverage_failed(&self, parse_result: &ParseResult) -> bool {
+        parse_result.coverage < self.coverage_threshold
+    }
+
+    /// D2 hook: if coverage falls below threshold, hand the partial off
+    /// to `ticket_emit::emit_ticket` and return the FailureTicket. Above
+    /// threshold returns `None` — the caller commits to AriGraph instead.
+    ///
+    /// Gated behind `contract-ticket` because the FailureTicket type
+    /// lives in `lance_graph_contract`. With the feature off, the hook
+    /// becomes a no-op `()` returner so the parser still compiles in
+    /// minimal builds.
+    #[cfg(feature = "contract-ticket")]
+    pub fn maybe_emit_ticket(
+        &self,
+        parse_result: &ParseResult,
+    ) -> Option<lance_graph_contract::grammar::FailureTicket> {
+        if !self.coverage_failed(parse_result) {
+            return None;
+        }
+        use lance_graph_contract::grammar::{PartialParse, TekamoloSlots};
+        let partial = PartialParse {
+            resolved_tokens: parse_result.resolved_tokens.clone(),
+            unresolved_tokens: parse_result.unresolved_tokens.clone(),
+            coverage: parse_result.coverage,
+        };
+        // TekamoloSlots / Wechsel / CausalAmbiguity stay empty until D3
+        // wires the Grammar Triangle; the ticket already routes correctly
+        // on `primes_found` + `classification_distance`.
+        Some(crate::ticket_emit::emit_ticket(
+            partial,
+            parse_result.coverage,
+            parse_result.classification_distance,
+            parse_result.primes_found,
+            TekamoloSlots::default(),
+            Vec::new(),
+            None,
+        ))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/deepnsm/src/ticket_emit.rs b/crates/deepnsm/src/ticket_emit.rs
@@ -0,0 +1,181 @@
+//! META-AGENT: add `pub mod ticket_emit;` to lib.rs. Gate behind feature
+//! `contract-ticket`. Also requires adding to Cargo.toml:
+//!   lance-graph-contract = { path = "../lance-graph-contract", optional = true }
+//!   [features] contract-ticket = ["dep:lance-graph-contract"]
+//!
+//! Emit FailureTicket from a partial DeepNSM parse for the LLM-tail router.
+//!
+//! See plan §D2 + grammar-tiered-routing.md "Combined failure ticket".
+//!
+//! Adapted to the actual `lance_graph_contract::grammar` surface:
+//! - `PartialParse { resolved_tokens, unresolved_tokens, coverage }`
+//! - `FailureTicket { partial_parse, attempted_inference, recommended_next,
+//!    causal_ambiguity, tekamolo, wechsel, coverage, missing_required }`
+//! - `TekamoloSlots { temporal, kausal, modal, lokal }` (no `has_unfillable`).
+//!
+//! `recommended_next` decision rules — the failure-mode IS the routing
+//! signal:
+//!
+//! - `primes_found < 4`              → `Abduction`               (NSM-thin → LLM names primes)
+//! - any TEKAMOLO slot unfillable    → `CounterfactualSynthesis` (slot must be hypothesised)
+//! - `classification_distance > 0.7` → `Extrapolation`           (novel domain marker)
+//! - else                            → `Revision`                (default refinement)
+
+#![cfg(feature = "contract-ticket")]
+
+use lance_graph_contract::grammar::{
+    CausalAmbiguity, FailureTicket, NarsInference, PartialParse, TekamoloSlots,
+    WechselAmbiguity,
+};
+
+/// Threshold above which `classification_distance` flags a novel domain.
+pub const NOVEL_DOMAIN_THRESHOLD: f32 = 0.7;
+
+/// Minimum NSM primes required before a parse is considered semantically
+/// thick enough to NOT need LLM abduction.
+pub const PRIMES_NEEDED: u8 = 4;
+
+/// Decompose a parse coverage failure into the SPO × 2³ × TEKAMOLO ×
+/// Wechsel fields the LLM router needs.
+///
+/// The caller checks `coverage_score >= LOCAL_COVERAGE_THRESHOLD` first —
+/// if so, no ticket is needed. Once we are here, we already know the
+/// parse failed coverage; we only need to choose the routing inference
+/// and stash the partial fields.
+pub fn emit_ticket(
+    partial: PartialParse,
+    coverage_score: f32,
+    classification_distance: f32,
+    primes_found: u8,
+    tekamolo: TekamoloSlots,
+    wechsel: Vec<WechselAmbiguity>,
+    causal_ambiguity: Option<CausalAmbiguity>,
+) -> FailureTicket {
+    let recommended = if primes_found < PRIMES_NEEDED {
+        NarsInference::Abduction
+    } else if has_unfillable(&tekamolo) {
+        NarsInference::CounterfactualSynthesis
+    } else if classification_distance > NOVEL_DOMAIN_THRESHOLD {
+        NarsInference::Extrapolation
+    } else {
+        NarsInference::Revision
+    };
+
+    FailureTicket {
+        partial_parse: partial,
+        attempted_inference: NarsInference::Deduction,
+        recommended_next: recommended,
+        causal_ambiguity,
+        tekamolo,
+        wechsel,
+        coverage: coverage_score,
+        missing_required: Vec::new(),
+    }
+}
+
+/// A TEKAMOLO slot is "unfillable" when the parser has none of the four
+/// adverbials filled. Local copy of the rule until the contract surfaces
+/// a more granular per-slot resolution flag.
+fn has_unfillable(slots: &TekamoloSlots) -> bool {
+    slots.is_empty()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use lance_graph_contract::grammar::wechsel::WechselRole;
+
+    fn empty_partial() -> PartialParse {
+        PartialParse {
+            resolved_tokens: vec![1, 2],
+            unresolved_tokens: vec![3, 4],
+            coverage: 0.5,
+        }
+    }
+
+    fn filled_tekamolo() -> TekamoloSlots {
+        TekamoloSlots {
+            temporal: Some((0, 1)),
+            kausal: Some((2, 3)),
+            modal: Some((4, 5)),
+            lokal: Some((6, 7)),
+        }
+    }
+
+    #[test]
+    fn low_primes_routes_to_abduction() {
+        let t = emit_ticket(
+            empty_partial(),
+            0.6,
+            0.1,
+            2,
+            filled_tekamolo(),
+            Vec::new(),
+            None,
+        );
+        assert_eq!(t.recommended_next, NarsInference::Abduction);
+        assert_eq!(t.coverage, 0.6);
+    }
+
+    #[test]
+    fn unfillable_tekamolo_routes_to_counterfactual_synthesis() {
+        let t = emit_ticket(
+            empty_partial(),
+            0.6,
+            0.1,
+            5,
+            TekamoloSlots::default(),
+            Vec::new(),
+            None,
+        );
+        assert_eq!(t.recommended_next, NarsInference::CounterfactualSynthesis);
+    }
+
+    #[test]
+    fn high_classification_distance_routes_to_extrapolation() {
+        let t = emit_ticket(
+            empty_partial(),
+            0.7,
+            0.85,
+            5,
+            filled_tekamolo(),
+            Vec::new(),
+            None,
+        );
+        assert_eq!(t.recommended_next, NarsInference::Extrapolation);
+    }
+
+    #[test]
+    fn default_path_is_revision() {
+        let t = emit_ticket(
+            empty_partial(),
+            0.7,
+            0.1,
+            5,
+            filled_tekamolo(),
+            Vec::new(),
+            None,
+        );
+        assert_eq!(t.recommended_next, NarsInference::Revision);
+    }
+
+    #[test]
+    fn wechsel_payload_passes_through() {
+        let amb = WechselAmbiguity {
+            token_index: 3,
+            candidates: vec![WechselRole::PrepTemporal, WechselRole::PrepSpatial],
+            local_ambiguity: 0.85,
+        };
+        let t = emit_ticket(
+            empty_partial(),
+            0.6,
+            0.1,
+            2,
+            filled_tekamolo(),
+            vec![amb],
+            None,
+        );
+        assert_eq!(t.wechsel.len(), 1);
+        assert_eq!(t.wechsel[0].token_index, 3);
+    }
+}
diff --git a/crates/deepnsm/src/triangle_bridge.rs b/crates/deepnsm/src/triangle_bridge.rs
