LangGraph: Guardrails and Fix Patterns

Use this page when your orchestration uses LangGraph (graph nodes, tool nodes, channels, subgraphs) and you see tool loops, wrong snippets, role mixing, or answers that flip between runs. The table maps symptoms to exact WFGY fix pages and gives a minimal recipe you can paste.

Acceptance targets

ΔS(question, retrieved) ≤ 0.45
Coverage ≥ 0.70 to the intended section or record
λ stays convergent across 3 paraphrases and 2 seeds
E_resonance stays flat on long windows

Open these first

Visual map and recovery
RAG Architecture & Recovery
End to end retrieval knobs
Retrieval Playbook
Why this snippet
Retrieval Traceability
Ordering control
Rerankers
Embedding vs meaning
Embedding ≠ Semantic
Hallucination and chunk edges
Hallucination
Long chains and entropy
Context Drift · Entropy Collapse
Structural collapse and recovery
Logic Collapse
Prompt injection and schema locks
Prompt Injection
Multi agent conflicts
Multi-Agent Problems
Bootstrap and deployment ordering
Bootstrap Ordering · Deployment Deadlock · Pre-Deploy Collapse
Snippet and citation schema
Data Contracts

Typical breakpoints and the right fix

Tool node returns free text instead of strict JSON
Fix: lock arguments, echo schema, and gate on validation.
Open: Prompt Injection · Data Contracts
Edges create a loop or the run never reaches a terminal node
Fix: add timeouts and BBCR bridge steps, log λ per hop, clamp variance with BBAM.
Open: Logic Collapse
High similarity yet wrong meaning
Fix: metric or index mismatch, or mixed write and read embeddings.
Open: Embedding ≠ Semantic
Hybrid routes worse than a single retriever
Fix: lock two stage query and add a deterministic reranker.
Open: Query Parsing Split · Rerankers
Facts exist in the store yet never surface
Fix: fragmentation or sharding misalignment.
Open: Vectorstore Fragmentation
Citations missing or inconsistent across nodes
Fix: require cite then explain and lock snippet fields.
Open: Retrieval Traceability · Data Contracts
Long running graphs change style and drift logically
Fix: split subgraphs and rejoin with BBCR, measure entropy and stop when it rises.
Open: Context Drift · Entropy Collapse
Role confusion between planner and worker nodes
Fix: stamp mem_rev and mem_hash, isolate namespaces, forbid cross section reuse.
Open: Multi-Agent Problems

Fix in 60 seconds

Measure ΔS
Compute ΔS(question, retrieved) and ΔS(retrieved, expected anchor).
Stable < 0.40, transitional 0.40 to 0.60, risk ≥ 0.60.
Probe λ_observe
Do a k sweep in retrieval. Reorder prompt headers. If λ flips, lock the schema and clamp with BBAM.
Apply the module

Retrieval drift → BBMC plus Data Contracts
Reasoning collapse → BBCR bridge plus BBAM, verify with Logic Collapse
Hallucination re entry after a fix → Pattern: Hallucination Re-entry

Verify
Coverage ≥ 0.70. ΔS ≤ 0.45. Three paraphrases and two seeds with λ convergent.

Minimal LangGraph topology with WFGY checks

# Pseudocode: focus on control points
from langgraph.graph import StateGraph, END

def retrieve(state):
    # k sweep and unified analyzer across dense and sparse
    return {"context": retriever.search(state["q"], k=10)}

def assemble(state):
    # schema-locked prompt with cite first
    msg = prompt.format(context=state["context"], question=state["q"])
    return {"msg": msg}

def reason(state):
    ans = llm.invoke(state["msg"])
    return {"answer": ans}

def wfgy_checks(state):
    # compute ΔS(question, context) and enforce thresholds
    # stop when ΔS ≥ 0.60 or λ divergent
    metrics = metrics_and_trace(state["q"], state["context"], state["answer"])
    if metrics["risk"]:
        return {"halt": True, "metrics": metrics}
    return {"metrics": metrics}

g = StateGraph(dict)
g.add_node("retrieve", retrieve)
g.add_node("assemble", assemble)
g.add_node("reason", reason)
g.add_node("wfgy_checks", wfgy_checks)

g.add_edge("retrieve", "assemble")
g.add_edge("assemble", "reason")
g.add_edge("reason", "wfgy_checks")
g.add_edge("wfgy_checks", END)

app = g.compile()

What this enforces

Retrieval is observable and parameterized. Analyzer and metric are unified across paths.
Prompt is schema locked with cite first. Snippet fields are required.
Post generation WFGY checks can halt the run when ΔS is high or λ flips.

Specs and recipes RAG Architecture & Recovery · Retrieval Playbook · Retrieval Traceability · Data Contracts

LangGraph specific gotchas

Mixed embedding functions between write and read. Rebuild with explicit metric and normalization. See Embedding ≠ Semantic
Event storms caused by branching edges. Add idempotency keys and dedupe on {source_id, mem_rev, index_hash}. See Retrieval Traceability
Subgraph recursion without a guard. Cap depth and time, insert BBCR bridge steps. See Logic Collapse
Memory modules re assert old facts after refresh. Stamp mem_rev and mem_hash. See pattern_memory_desync
Streams are merged without source fences. Add per source headers and forbid cross section reuse. See pattern_symbolic_constraint_unlock

When to escalate

ΔS remains ≥ 0.60 Rebuild the index using the checklists and verify with a small gold set. Retrieval Playbook
Identical input yields different answers across runs Check version skew and session state. Pre-Deploy Collapse

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

🧭 Explore More

Module	Description	Link
WFGY Core	WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack	View →
Problem Map 1.0	Initial 16-mode diagnostic and symbolic fix framework	View →
Problem Map 2.0	RAG-focused failure tree, modular fixes, and pipelines	View →
Semantic Clinic Index	Expanded failure catalog: prompt injection, memory bugs, logic drift	View →
Semantic Blueprint	Layer-based symbolic reasoning & semantic modulations	View →
Benchmark vs GPT-5	Stress test GPT-5 with full WFGY reasoning suite	View →
🧙‍♂️ Starter Village 🏡	New here? Lost in symbols? Click here and let the wizard guide you through	Start →