---
name: semantics-belief
description: Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.
---

# [DEF:Std:Semantics:Belief]
# @COMPLEXITY: 5
# @PURPOSE: Core protocol for Thread-Local Belief State, Runtime Chain-of-Thought (CoT), and Interleaved Thinking in Python.
# @RELATION: DEPENDS_ON -> [Std:Semantics:Core]
# @INVARIANT: Implementation of C4/C5 complexity nodes MUST emit reasoning via semantic logger methods before mutating state or returning.

## 0. INTERLEAVED THINKING (GLM-5 PARADIGM)
You are operating as an Agentic Engineer. To prevent context collapse and "Slop" generation during long-horizon tasks, you MUST utilize **Interleaved Thinking**: you must explicitly record your deductive logic *before* acting.
In this architecture, we do not use arbitrary inline comments for CoT. We compile your reasoning directly into the runtime using the **Thread-Local Belief State Logger**. This allows the AI Swarm to trace execution paths mathematically and prevents regressions. 

## I. THE BELIEF STATE API (STRICT SYNTAX)
The logging architecture uses thread-local storage (`_belief_state`). The active `ID` of the semantic anchor is injected automatically. You MUST NOT hallucinate context objects.

**[MANDATORY IMPORTS]:**
`from ...core.logger import logger, belief_scope, believed`

**[EXECUTION BOUNDARIES]:**
1. **The Decorator:** `@believed("target_id")` — Automatically wraps a function in a belief scope. Use this for top-level entry points.
2. **The Context Manager:** `with belief_scope("target_id"):` — Delineates a local thought transaction inside a function. 
   - **CRITICAL RULE:** Do NOT yield a context variable. Write strictly `with belief_scope("id"):`, NOT `with belief_scope("id") as ctx:`. The state is thread-local.

## II. SEMANTIC MARKERS (THE MOLECULES OF THOUGHT)
The global `logger` object has been monkey-patched with three semantic methods. The formatter automatically prepends the `[ID]` and the `[MARKER]` (e.g., `[execute_tx][REASON]`). 
**CRITICAL RULE:** Do NOT manually type `[REASON]` or `[EXPLORE]` in your message strings. Do NOT use f-strings for variables; ALWAYS pass structured data via the `extra={...}` parameter.

**1. `logger.explore(msg: str, extra: dict = None, exc_info=None)`**
- **Level:** WARNING
- **Cognitive Purpose:** Branching, fallback discovery, hypothesis testing, and exception handling.
- **Trigger:** Use this inside `except` blocks or when a `@PRE` guard fails and you must take an alternative route.
- **Rule:** Always pass the caught exception via `exc_info=e`.
- **Example:** `logger.explore("Primary API timeout. Falling back to cache.", extra={"timeout": 5}, exc_info=e)`

**2. `logger.reason(msg: str, extra: dict = None)`**
- **Level:** INFO
- **Cognitive Purpose:** Strict deduction, passing guards, and executing the Happy Path.
- **Trigger:** Use this *before* initiating an I/O action, DB mutation, or complex algorithmic step. This is your "Action Intent".
- **Example:** `logger.reason("Input validated. Initiating ledger transaction.", extra={"amount": amount})`

**3. `logger.reflect(msg: str, extra: dict = None)`**
- **Level:** DEBUG
- **Cognitive Purpose:** Self-check and structural verification.
- **Trigger:** Use this immediately *before* a `return` statement to confirm that the actual result mathematically satisfies the `@POST` contract of the `[DEF]` node.
- **Example:** `logger.reflect("Transaction committed successfully. Guarantee met.", extra={"tx_id": tx.id})`

## III. ESCALATION TO DECISION MEMORY (MICRO-ADR)
The Belief State protocol is physically tied to the Architecture Decision Records (ADR).
If your execution path triggers a `logger.explore()` due to a broken assumption (e.g., a library bug, a missing DB column) AND you successfully implement a workaround that survives into the final code:
**YOU MUST ASCEND TO THE `[DEF]` HEADER AND DOCUMENT IT.**
You must add `@RATIONALE: [Why you did this]` and `@REJECTED:[The path that failed during explore()]`. 
Failure to link a runtime `explore` to a static `@REJECTED` tag is a fatal protocol violation that causes amnesia for future agents.
# [/DEF:Std:Semantics:Belief]
**[SYSTEM: END OF BELIEF DIRECTIVE. ENFORCE STRICT RUNTIME CoT.]**