docs(contract): two runnable Elixir-style orchestration deep-dive examples

examples/cognitive_cycle.rs — the active-inference loop: a ThoughtCtx piped
through a tactic recipe (Elixir |> over the uniform `Tactic` behaviour),
marker-gated (Gate-bucket tactics skip in FLOW), looping until free energy
descends below the homeostasis floor ("shader rests"). Runs to rest in 2
rounds; narrates every step (which tactic fired, bucket, Δconf, gate state).

examples/savant_dispatch.rs — Odoo savant delegation: AXIS-A guard (woa-rs)
delegates the ambiguous core to a savant; dispatch is the data tuple
(family · ReasoningKind · InferenceType→QueryStrategy · Semiring · Style),
pattern-matched on ReasoningKind (Elixir case). Real savants from the roster
(PaymentToInvoiceMatcher / AutopostRecommender / FiscalPositionResolver /
SequenceGapAnomalyDetector); output is a NARS suggestion, never an un-guarded
write (Iron Rule 7).

Both `cargo run -p lance-graph-contract --example <name>` — genuine (every
call is a real contract kernel/type), self-explanatory, for a quick deep-dive.

https://claude.ai/code/session_017GFLBnDy23AWBqvkbHHC41

Author: claude

crates/lance-graph-contract/examples/cognitive_cycle.rs

@@ -0,0 +1,76 @@
+//! Orchestration deep-dive #1 — the active-inference cognitive cycle.
+//!
+//! Run it:  `cargo run -p lance-graph-contract --example cognitive_cycle`
+//!
+//! THE IDEA (Elixir-style):
+//!   * every reasoning tactic implements ONE behaviour — `Tactic` (meta/gate/apply/run),
+//!     exactly like an Elixir `@behaviour` / GenServer callback.
+//!   * a "recipe" is a *pipeline* of tactics (the Elixir `|>` operator), applied in order.
+//!   * each tactic is **clock-gated** by markers: a Gate-bucket tactic only fires when there
+//!     is surprise to act on (CollapseGate SD not in FLOW). Most stay dark — like a CPU.
+//!   * the loop runs until free energy descends below the homeostasis floor: "the shader
+//!     can't resist the thinking… F descends, bits clear, shader rests."
+//!
+//! Nothing here is a toy: every call is a real `lance_graph_contract` kernel.
+
+use lance_graph_contract::recipe_kernels::{kernel, GateState, ThoughtCtx, SD_FLOW};
+use lance_graph_contract::recipes::recipe_by_code;
+
+/// A "deep-think" recipe = an ordered pipeline of tactics (by their catalogue code).
+/// Read it top-to-bottom like an Elixir pipe:
+///   ctx |> Expand |> Decompose |> Prune |> Contradiction |> Converge |> Meta |> Filter |> Reduce
+const DEEP_THINK: [&str; 8] = ["RTE", "HTD", "TCP", "CR", "CDT", "MCP", "TCF", "CUR"];
+
+fn gate_state(sd: f32) -> GateState {
+    if sd < SD_FLOW { GateState::Flow } else if sd <= 0.35 { GateState::Hold } else { GateState::Block }
+}
+
+fn main() {
+    // A *surprised* starting state: high dispersion (SD=BLOCK), high free energy,
+    // four candidate interpretations, and a same-topic contradiction in the belief set.
+    let mut ctx = ThoughtCtx::new(vec![0.92, 0.61, 0.34, 0.12]);
+    ctx.sd = 0.42; // > 0.35 → BLOCK: the gate is wide open, deep tactics will fire
+    ctx.free_energy = 0.80;
+    ctx.confidence = 0.50;
+    ctx.beliefs = vec![(7, 0.90, 0.8), (7, 0.10, 0.7)]; // topic 7 asserted true AND false
+
+    println!("== cognitive cycle: one Think, run to rest ==\n");
+    println!("start: gate={:?} F={:.2} conf={:.2} candidates={} beliefs={}\n",
+        gate_state(ctx.sd), ctx.free_energy, ctx.confidence, ctx.candidates.len(), ctx.beliefs.len());
+
+    // The active-inference loop: keep thinking while there is surprise (gate != FLOW).
+    let mut round = 0;
+    while gate_state(ctx.sd) != GateState::Flow && round < 5 {
+        round += 1;
+        println!("── round {round} (gate {:?}) ───────────────────────", gate_state(ctx.sd));
+
+        // Pipe the context through the recipe. Each step is `ctx |> tactic`.
+        for code in DEEP_THINK {
+            let rec = recipe_by_code(code).expect("recipe in catalogue");
+            let k = kernel(rec.id).expect("kernel for id");
+            let out = k.run(&mut ctx); // gate + apply; confidence auto-clamped
+            println!(
+                "  {:<5} [{:<12}] {:<22} {}  (Δconf {:+.2})",
+                code,
+                format!("{:?}", rec.bucket),
+                rec.name,
+                if out.fired { out.note } else { "· gated off (FLOW)" },
+                out.delta_conf,
+            );
+        }
+
+        // The cycle resolved some surprise: dispersion + free energy anneal toward rest.
+        // (In the wired system this falls out of the codec sweep; here we make it explicit.)
+        ctx.sd *= 0.55;
+        ctx.free_energy *= 0.5;
+        println!("  → after round: gate={:?} SD={:.3} F={:.3} conf={:.2}\n",
+            gate_state(ctx.sd), ctx.sd, ctx.free_energy, ctx.confidence);
+    }
+
+    println!("== rest ==  the shader stopped because gate reached {:?} (SD={:.3} < FLOW {SD_FLOW}).",
+        gate_state(ctx.sd), ctx.sd);
+    println!("final: conf={:.2}, {} candidate(s) survived pruning, {} beliefs.",
+        ctx.confidence, ctx.candidates.len(), ctx.beliefs.len());
+    println!("\nKey: Gate-bucket tactics (TCP/CDT/TCF/CUR) skip while in FLOW — the markers,");
+    println!("not a scheduler, decide what fires. Same `Tactic` behaviour, 34 hot-swappable units.");
+}

crates/lance-graph-contract/examples/savant_dispatch.rs

@@ -0,0 +1,74 @@
+//! Orchestration deep-dive #2 — Odoo savant delegation (woa-rs AXIS-A guard → lance-graph AXIS-B reason).
+//!
+//! Run it:  `cargo run -p lance-graph-contract --example savant_dispatch`
+//!
+//! THE IDEA (Elixir-style):
+//!   * a Savant is a delegated reasoner declared as a *tuple* (family · ReasoningKind ·
+//!     InferenceType · SemiringChoice · StyleCluster) — the tuple FULLY determines dispatch.
+//!   * dispatch is **pattern-matching** on `ReasoningKind` (like an Elixir `case`/multi-clause
+//!     function head), and the `InferenceType` resolves O(1) to a `QueryStrategy`.
+//!   * the deterministic guard (AXIS-A) stays in woa-rs; only the *ambiguous core* is delegated
+//!     here (AXIS-B), and the answer is a NARS-truth-weighted **suggestion**, never an
+//!     un-guarded write (Iron Rule 7).
+
+use lance_graph_contract::reasoning::ReasoningKind;
+use lance_graph_contract::savants::{savant_by_name, Savant};
+
+/// A concrete situation arriving from the ERP.
+struct Situation {
+    headline: &'static str,
+    /// The AXIS-A guard already ran in woa-rs; `true` means it could NOT decide deterministically
+    /// and is delegating the ambiguous core to the savant.
+    ambiguous: bool,
+    savant: &'static str,
+}
+
+/// Pattern-match the kind → the reasoning approach (the Elixir multi-clause `case`).
+fn approach(kind: ReasoningKind) -> &'static str {
+    match kind {
+        ReasoningKind::CustomerCategory => "classify against the family codebook (deductive lookup)",
+        ReasoningKind::PostingAnomaly => "abduce the most likely cause from the evidence trail",
+        ReasoningKind::NextBestAction => "induce the action with the highest expected value",
+        ReasoningKind::InvoiceCompleteness => "check required-field coverage, score the gaps",
+        ReasoningKind::MailIntent => "resonate the message against intent prototypes",
+        ReasoningKind::Other(code) => match code {
+            5 | 6 => "match open items / bank lines by evidence fusion (reconcile)",
+            _ => "domain-specific Other(code) reasoner",
+        },
+    }
+}
+
+fn dispatch(s: &Savant) {
+    println!("  savant     {} (#{}, lane {})", s.name, s.id, s.lane);
+    println!("  family     {}", s.family.map(|f| format!("0x{f:02X}")).unwrap_or_else(|| "None (needs alignment axiom)".into()));
+    println!("  tuple      kind={:?} · infer={:?} · semiring={:?} · style={:?}", s.kind, s.inference, s.semiring, s.style);
+    // The InferenceType resolves O(1) to the runtime query strategy.
+    println!("  → strategy {:?}   (InferenceType::default_strategy)", s.query_strategy());
+    println!("  → approach {}", approach(s.kind));
+    println!("  → output   NARS (frequency, confidence) suggestion — woa-rs applies it behind its AXIS-A guard\n");
+}
+
+fn main() {
+    println!("== Odoo savant delegation: AXIS-A guard (woa-rs) → AXIS-B reason (lance-graph) ==\n");
+
+    let inbox = [
+        Situation { headline: "€1,200 payment arrived — does it fully reconcile the partner's open invoices?", ambiguous: true, savant: "PaymentToInvoiceMatcher" },
+        Situation { headline: "3rd identical bill from this vendor, unmodified — auto-post it?",              ambiguous: true, savant: "AutopostRecommender" },
+        Situation { headline: "new B2B partner in AT — which fiscal position (tax mapping)?",                 ambiguous: true, savant: "FiscalPositionResolver" },
+        Situation { headline: "journal sequence jumps 1042 → 1044 — is 1043 a deleted posted entry?",         ambiguous: true, savant: "SequenceGapAnomalyDetector" },
+        Situation { headline: "invoice with a perfectly matching single open item",                           ambiguous: false, savant: "ReconcileMatchSelector" },
+    ];
+
+    for s in &inbox {
+        println!("• {}", s.headline);
+        if !s.ambiguous {
+            println!("  AXIS-A (woa-rs): deterministic match — applied directly, NO delegation.\n");
+            continue;
+        }
+        let sv = savant_by_name(s.savant).expect("savant in roster");
+        dispatch(sv);
+    }
+
+    println!("Same delegation tuple for all 25 savants; dispatch is data, not branches.");
+    println!("Pattern-match on ReasoningKind picks the approach; the family's StyleCluster colours it.");
+}