docs: commenti inline sul perché in core/induttivo/lambda_space

core.py

@@ -86,6 +86,9 @@ def _peso_sequitur() -> float:
 
 # ─── helpers numerici ────────────────────────────────────────────────────────
 
+# NLI/embedding/numpy lasciano scalari e array numpy dentro i dict che finiscono
+# in yaml_out → json.dumps si spezzerebbe su np.float32/np.bool_ senza questa
+# normalizzazione preventiva (RapportoResh dev'essere serializzabile as-is).
 def _to_native(obj):
     if isinstance(obj, dict):
         return {k: _to_native(v) for k, v in obj.items()}
@@ -295,6 +298,12 @@ async def analizza_async(
     integrita_io, integrita_dett = await _run_in_thread(_valuta_io, teleologia, fonte=obiettivo_fonte)
 
     # verifiche logiche: 1 verifica per argomento (fallacia O non-sequitur ⇒ non valido)
+    # Nessun indice condiviso lega Argomento (dalle proposizioni segmentate) alle
+    # Patologia (span sul testo grezzo): vengono da passaggi diversi sulla stessa
+    # frase. Si riallineano ri-cercando il testo dell'argomento nel documento e
+    # controllando se cade dentro (o poco dopo, +200 char di margine per code
+    # di frase/punteggiatura) lo span della fallacia — match grossolano ma l'unico
+    # disponibile senza rifare la segmentazione con offset condivisi.
     verifiche: list[VerificaLogica] = []
     fallacy_spans = [(p.span_char, p.dettaglio.get("fallacia_l2", "?"))
                      for p in fallacie_pats if p.span_char]
@@ -415,6 +424,10 @@ async def analizza_async(
             ))
 
     patologie_legacy = [p.as_message() for p in pat_struct]
+    # Soglia euristica (non calibrata su corpus, come i pesi in epsilon.py): un
+    # testo con ε quasi perfetto e zero patologie è sospetto quanto uno basso —
+    # potrebbe segnalare che il dubbio (ऋ) non sta esercitando abbastanza
+    # resistenza contro la certezza (Θ), non che il testo sia davvero impeccabile.
     if eps_resh > 0.95:
         patologie_legacy.append("ε_ऋ molto alto: verificare bilanciamento con Θ (rischio paralisi)")
 

induttivo.py

@@ -330,6 +330,11 @@ def pre_detect_trilemma(testo: str, rapporto_resh=None) -> list[TrilemmaHit]:
     hits: list[TrilemmaHit] = _scan_markers(testo, _load_trilemma_markers())
 
     # 2. Segnali dal deterministico (se disponibile).
+    # Sconto ×0.8 sulla confidence: qui si sta REINTERPRETANDO un segnale nato
+    # per un altro scopo (NON_SEQUITUR/circolarità di sequitur.py) come hit
+    # Trilemma — un'inferenza su cosa implica il pattern, non una rilevazione
+    # diretta del corno. Meno affidabile del match regex diretto (_scan_markers),
+    # quindi pesa meno nel confronto det/ind di _confronta_trilemma.
     if rapporto_resh is not None:
         for pat in getattr(rapporto_resh, "patologie_strutturate", []):
             tipo_val = getattr(pat.tipo, "value", str(pat.tipo))
@@ -706,6 +711,9 @@ def analizza_induttivo(
         from .lambda_space import G, resolve
         O = resolve(G.ESTRAI_OBIETTIVO)(testo)    # lazy: Λ spina dorsale
 
+    # arsenale/trilemma restano fuori da `da_eseguire`: non sono saltati, hanno
+    # ciascuno il proprio blocco dedicato più sotto (payload/feed diversi dal
+    # generico _OUT_GENERICO — trilemma riceve pure Arsenale + ऋ¹ come contesto).
     da_eseguire = assi if assi is not None else [a for a, _ in _ASSI if a not in ("arsenale", "trilemma")]
 
     # 2. Arsenale (3 assi + contrasto in una call).

lambda_space.py

@@ -117,6 +117,9 @@ def __str__(self) -> str:
 
 
 # ─── registry Λ_ऋ ──────────────────────────────────────────────────────
+# frozenset, non list/dict: Λ non si muta a runtime — evolve solo aggiungendo
+# un Gamma() qui nel codice (nuovo commit), mai con un .add()/.pop() dell'agente
+# durante un'analisi. L'immutabilità è la garanzia, non un dettaglio di tipo.
 
 LAMBDA_RESH: frozenset[Gamma] = frozenset({
 
@@ -1004,4 +1007,6 @@ def _audit_invariants() -> None:
             assert g.eps_feeds == (), f"{g.name}: eps_feeds assegnato ma eps_role={g.eps_role!r}"
 
 
+# Eseguito a IMPORT time (non lazy): un invariante rotto deve fermare il modulo
+# subito, non emergere a metà run quando un core prova a risolvere un γ malformato.
 _audit_invariants()