@noeva/analytics-core 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 Le versioni del pacchetto che i repository dei progetti installano (ADR 0005). Prima di
 `analytics upgrade` si legge cosa cambia fra la versione installata e la nuova.
 
+## 0.5.1 — 12 novembre 2026
+
+- Il servizio MCP dei PC (`noeva-<id>.exe`) non si blocca piu' su una query lenta
+  (11/11/2026). Gli strumenti di Wren erano sincroni e giravano nell'event loop:
+  una query lunga fermava tutte le altre richieste e l'annullamento. Ora run_sql,
+  dry_run e query_cube girano in piu' thread, ognuno con la sua connessione
+  (`connessioni` in noeva.json, 3 per il vivo), con un tempo massimo per query
+  (`limite_query_s`, 120 s) fatto rispettare dal driver ODBC, che annulla la query su
+  SQL Server, e dal servizio stesso se il driver non basta. Claude riceve un errore
+  che dice di ridurre il periodo, non di riprovare in parallelo. Quando Claude annulla
+  la richiesta MCP, la query si ferma anche sul database (`server/esecuzione.py`).
+- `noeva-<id>.exe --verifica` dice se il servizio aperto in Claude ha una query in
+  corso oltre il tempo massimo (il file di stato nella cartella temporanea), e in quel
+  caso chiude con un problema.
+- Le regole delle query sul vivo (un mese poi l'anno, mai query pesanti in parallelo,
+  aggregare prima di unire, ridurre il periodo dopo un timeout) stanno in
+  `lib/modello/istruzioni.json` (`regole_query`): nelle istruzioni di initialize, in
+  locale e dal gateway, e nella scheda `00-progetto`, che arriva col modello
+  pubblicato anche ai servizi gia' installati. Anche nella descrizione di run_sql.
+- Per le nuove regole nella scheda il progetto ripubblica il modello
+  (`analytics modello`, il job `pubblica` della CI); per il tempo massimo e le
+  connessioni serve un rilascio dell'eseguibile (`rilascio-windows.yml`).
+
 ## 0.5.0 — 12 novembre 2026
 
 - **L'AI passa solo da NOEVA.** I moduli di pagina non offrono piu' la CLI di Claude:

package/contenuto/lib/mcp-locale/costruisci.py

@@ -261,6 +261,10 @@ def argomenti_pyinstaller(nome: str, build: pathlib.Path) -> list:
         # e dal repository si compila con le trasformazioni di lib/modello/consegna.py.
         "--paths", QUI / "server", "--paths", QUI.parent / "modello",
         "--hidden-import", "modello_locale", "--hidden-import", "consegna", "--hidden-import", "scheda",
+        # Le query in thread, col tempo massimo e l'annullamento (server/esecuzione.py);
+        # la scheda legge le regole delle query da istruzioni.json, che sta accanto al modulo.
+        "--hidden-import", "esecuzione", "--hidden-import", "istruzioni",
+        "--add-data", f"{QUI.parent / 'modello' / 'istruzioni.json'}{os.pathsep}.",
         QUI / "server" / "noeva_mcp.py",
     ]
 

package/contenuto/lib/mcp-locale/server/esecuzione.py

@@ -0,0 +1,405 @@
+"""Come il servizio locale esegue le query: piu' connessioni, un tempo massimo, l'annullamento.
+
+L'11/11/2026 il connettore di un cliente e' rimasto fermo mezz'ora: quattro query pesanti
+lanciate in parallelo, nessuna finita, e nel frattempo nessuna risposta, nemmeno
+alle richieste piu' semplici. Il motivo: nel server MCP di Wren (wrenai 0.15) gli
+strumenti sono funzioni sincrone, e FastMCP (mcp 1.30) le chiama dentro l'event
+loop. Una query lunga fermava tutto il processo: le altre richieste, i ping e
+l'annullamento di Claude. Da fuori sembrava spento.
+
+Qui gli strumenti che toccano il database (run_sql, dry_run, query_cube) diventano
+asincroni e girano in un gruppo di thread, ognuno con il suo motore e la sua
+connessione:
+
+- una query lenta occupa un thread, le altre passano sugli altri (`connessioni`,
+  3 per il database vivo);
+- ogni query ha un tempo massimo (`limite_query_s`, 120 s): lo fa rispettare il
+  driver ODBC (il timeout della connessione, che su SQL Server annulla davvero la
+  query sul server); se non bastasse, allo scadere piu' un margine il servizio
+  annulla il cursore lui stesso e risponde comunque;
+- quando Claude annulla la richiesta MCP (notifications/cancelled) il servizio
+  annulla il cursore: la query si ferma anche sul database;
+- l'errore del tempo scaduto dice a Claude cosa fare: ridurre il periodo, non
+  rilanciare la stessa query ne' spezzarla in parallelo.
+
+Le query in corso stanno in un file di stato nella cartella temporanea, riscritto
+ogni pochi secondi da un thread a parte: `--verifica` lo legge e dice se una query
+e' in corso da troppo tempo (stato_in_corso).
+
+Niente qui importa mcp o wren: si prova con un motore finto (test/test_esecuzione.py).
+Niente stampa su stdout: e' il canale MCP.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import pathlib
+import tempfile
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable
+
+LIMITE_S = 120
+CONNESSIONI = 3
+# Oltre il limite del driver: il tempo che il driver ha per annullare e rispondere
+# prima che il servizio annulli il cursore da se'.
+MARGINE_S = 15
+# Ogni quanto il file di stato si riscrive; oltre STATO_VECCHIO_S il servizio che lo
+# scriveva non c'e' piu'.
+BATTITO_S = 5
+STATO_VECCHIO_S = 60
+
+# Gli strumenti di Wren che vanno sul database.
+STRUMENTI_DB = ("run_sql", "dry_run", "query_cube")
+
+REGOLE = (
+    "Il database e' quello di produzione, che usa anche il gestionale: ogni query ha un tempo "
+    "massimo di {minuti}. Prima prova la query su un mese, poi allarga all'anno. Una query pesante "
+    "alla volta, mai in parallelo. Aggrega ogni tabella (GROUP BY) prima di unirla alle altre: mai "
+    "un join riga per riga tra tabelle grandi (per esempio listino e fatture). Se una query va in "
+    "timeout riduci il periodo o le colonne, non spezzarla in piu' query in parallelo."
+)
+
+
+def minuti(secondi: float) -> str:
+    if secondi % 60 == 0:
+        m = int(secondi // 60)
+        return "1 minuto" if m == 1 else f"{m} minuti"
+    return f"{int(secondi)} secondi"
+
+
+def regole_testo(limite_s: float = LIMITE_S) -> str:
+    return REGOLE.format(minuti=minuti(limite_s))
+
+
+class TempoScaduto(Exception):
+    """La query ha superato il tempo massimo ed e' stata annullata."""
+
+    def __init__(self, limite_s: float):
+        super().__init__(
+            f"NOEVA ha fermato la query dopo {minuti(limite_s)}, il tempo massimo, e l'ha annullata anche "
+            "sul database. Non rilanciarla uguale e non dividerla in piu' query da lanciare in parallelo: "
+            "finirebbero in coda e scadrebbero anche quelle. Riducila: prova su un solo mese, poi allarga; "
+            "aggrega ogni tabella (GROUP BY) prima di unirla alle altre, mai un join riga per riga "
+            "(per esempio listino con fatture); togli le colonne che non servono."
+        )
+
+
+def e_un_timeout(e: BaseException | None) -> bool:
+    """Il timeout del driver, dentro gli errori che Wren avvolge (WrenError, DatabaseTimeoutError)."""
+    visti = 0
+    while e is not None and visti < 10:
+        if isinstance(e, (TimeoutError, TempoScaduto)) or type(e).__name__ == "DatabaseTimeoutError":
+            return True
+        testo = str(e)
+        if "HYT00" in testo or "timeout expired" in testo.lower():
+            return True
+        e = e.__cause__ or e.__context__
+        visti += 1
+    return False
+
+
+def connessione_persa(e: BaseException | None) -> bool:
+    """Errori dopo i quali la connessione non serve piu' (rete, server riavviato)."""
+    visti = 0
+    while e is not None and visti < 10:
+        testo = str(e)
+        if any(s in testo for s in ("08S01", "08003", "08001", "Communication link failure")):
+            return True
+        e = e.__cause__ or e.__context__
+        visti += 1
+    return False
+
+
+class Annullabile:
+    """Una connessione pyodbc che ricorda il cursore in uso, per annullarlo da un altro thread.
+
+    Il connettore MSSQL di Wren apre un cursore per query e non lo espone;
+    pyodbc permette Cursor.cancel() da un altro thread, ed e' il modo di fermare
+    la query sul server."""
+
+    def __init__(self, connessione: Any):
+        object.__setattr__(self, "_connessione", connessione)
+        object.__setattr__(self, "corrente", None)
+
+    def cursor(self, *a, **k):
+        c = self._connessione.cursor(*a, **k)
+        object.__setattr__(self, "corrente", c)
+        return c
+
+    def annulla(self) -> None:
+        c = self.corrente
+        if c is not None:
+            try:
+                c.cancel()
+            except Exception:  # noqa: BLE001 - cursore gia' chiuso: niente da annullare
+                pass
+
+    def __getattr__(self, nome: str):
+        return getattr(self._connessione, nome)
+
+    def __setattr__(self, nome: str, valore: Any) -> None:
+        setattr(self._connessione, nome, valore)
+
+
+def annulla_motore(motore: Any) -> None:
+    """Ferma la query in corso sul motore: il cursore su SQL Server, interrupt() su DuckDB."""
+    connettore = getattr(motore, "_connector", None)
+    conn = getattr(connettore, "connection", None)
+    if isinstance(conn, Annullabile):
+        conn.annulla()
+    elif conn is not None and hasattr(conn, "interrupt"):
+        try:
+            conn.interrupt()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def rendi_annullabile(motore: Any) -> Any:
+    """Avvolge la connessione del motore appena si apre (il connettore di Wren e' pigro)."""
+    originale = motore._get_connector
+
+    def apri():
+        c = originale()
+        conn = getattr(c, "connection", None)
+        if conn is not None and hasattr(conn, "cursor") and not hasattr(conn, "interrupt") \
+                and not isinstance(conn, Annullabile):
+            c.connection = Annullabile(conn)
+        return c
+
+    motore._get_connector = apri
+    return motore
+
+
+class Lavoro:
+    def __init__(self, descrizione: str):
+        self.descrizione = descrizione
+        self.creato = time.time()
+        self.inizio: float | None = None  # time.monotonic() quando un thread lo prende
+        self.inizio_epoch: float | None = None
+        self.annullato = False
+        self.motore: Any = None
+
+    def annulla(self) -> None:
+        self.annullato = True
+        if self.motore is not None:
+            annulla_motore(self.motore)
+
+
+def _lascia(futuro: asyncio.Future) -> None:
+    """Un lavoro che non si attende piu': il suo errore (l'annullamento) non va nel log."""
+    futuro.add_done_callback(lambda f: f.cancelled() or f.exception())
+
+
+class Postazioni:
+    """I thread che eseguono le query, ognuno col suo motore e la sua connessione.
+
+    `crea_motore()` fa un motore nuovo (senza aprire la connessione: Wren la apre
+    alla prima query). `motore()` e' quello del thread corrente: nei thread delle
+    query il suo, altrove quello di base, che serve agli strumenti senza database
+    (dry_plan, list_functions) e non apre mai una connessione."""
+
+    def __init__(self, crea_motore: Callable[[], Any], connessioni: int = CONNESSIONI,
+                 limite_s: float = LIMITE_S, margine_s: float = MARGINE_S,
+                 stato: pathlib.Path | None = None, server: str = ""):
+        self._crea = crea_motore
+        self.connessioni = max(1, int(connessioni))
+        self.limite_s = float(limite_s)
+        self.margine_s = float(margine_s)
+        self._locale = threading.local()
+        self._motori: list[Any] = []
+        self._blocco = threading.Lock()
+        self._lavori: set[Lavoro] = set()
+        self._pool = ThreadPoolExecutor(max_workers=self.connessioni, thread_name_prefix="noeva-query")
+        self.base = crea_motore()
+        self.server = server
+        self.stato = stato
+        self._fermo = threading.Event()
+        if stato is not None:
+            threading.Thread(target=self._battito, name="noeva-stato", daemon=True).start()
+
+    # --- i motori ---------------------------------------------------------------
+    def motore(self) -> Any:
+        m = getattr(self._locale, "motore", None)
+        return m if m is not None else self.base
+
+    def _motore_del_thread(self) -> Any:
+        m = getattr(self._locale, "motore", None)
+        if m is None:
+            m = rendi_annullabile(self._crea())
+            self._locale.motore = m
+            with self._blocco:
+                self._motori.append(m)
+        return m
+
+    # --- l'esecuzione -------------------------------------------------------------
+    def _lavora(self, lavoro: Lavoro, fn: Callable[[], Any]) -> Any:
+        if lavoro.annullato:
+            raise asyncio.CancelledError("annullata prima di partire")
+        m = self._motore_del_thread()
+        lavoro.motore = m
+        lavoro.inizio = time.monotonic()
+        lavoro.inizio_epoch = time.time()
+        try:
+            return fn()
+        except Exception as e:
+            if connessione_persa(e):
+                # La prossima query riapre la connessione invece di fallire per sempre.
+                try:
+                    m.close()
+                except Exception:  # noqa: BLE001
+                    pass
+            if e_un_timeout(e):
+                raise TempoScaduto(self.limite_s) from e
+            raise
+        finally:
+            lavoro.motore = None
+
+    async def esegui(self, fn: Callable[[], Any], descrizione: str = "") -> Any:
+        """Esegue fn in un thread delle query; fn usa motore(), cioe' il motore di quel thread.
+
+        Il tempo si conta da quando un thread prende il lavoro, non dalla coda: in
+        coda si aspetta che una query finisca o scada."""
+        lavoro = Lavoro(descrizione)
+        with self._blocco:
+            self._lavori.add(lavoro)
+        futuro = asyncio.wrap_future(self._pool.submit(self._lavora, lavoro, fn))
+        try:
+            while True:
+                fatti, _ = await asyncio.wait({futuro}, timeout=0.5)
+                if fatti:
+                    return futuro.result()
+                if lavoro.inizio is not None and time.monotonic() - lavoro.inizio > self.limite_s + self.margine_s:
+                    # Il driver non l'ha fermata (la lettura delle righe, un driver
+                    # senza timeout): la si annulla da qui e si risponde comunque.
+                    lavoro.annulla()
+                    _lascia(futuro)
+                    raise TempoScaduto(self.limite_s)
+        except asyncio.CancelledError:
+            # Claude ha annullato la richiesta: la query si ferma anche sul database.
+            lavoro.annulla()
+            futuro.cancel()
+            _lascia(futuro)
+            raise
+        finally:
+            with self._blocco:
+                self._lavori.discard(lavoro)
+
+    def chiudi(self) -> None:
+        self._fermo.set()
+        with self._blocco:
+            lavori = list(self._lavori)
+            motori = list(self._motori)
+        for lv in lavori:
+            lv.annulla()
+        self._pool.shutdown(wait=False, cancel_futures=True)
+        for m in [*motori, self.base]:
+            try:
+                m.close()
+            except Exception:  # noqa: BLE001
+                pass
+        if self.stato is not None:
+            try:
+                self.stato.unlink()
+            except OSError:
+                pass
+
+    # --- lo stato per --verifica ----------------------------------------------------
+    def fotografia(self) -> dict:
+        with self._blocco:
+            lavori = list(self._lavori)
+        return {
+            "server": self.server,
+            "pid": os.getpid(),
+            "aggiornato": time.time(),
+            "limite_s": self.limite_s,
+            "connessioni": self.connessioni,
+            "lavori": [
+                {"in_coda": lv.inizio_epoch is None, "dal": lv.inizio_epoch or lv.creato,
+                 "query": lv.descrizione[:300]}
+                for lv in sorted(lavori, key=lambda x: x.creato)
+            ],
+        }
+
+    def _battito(self) -> None:
+        while not self._fermo.is_set():
+            scrivi_stato(self.stato, self.fotografia())
+            self._fermo.wait(BATTITO_S)
+
+
+class MotoreCorrente:
+    """Al posto di ctx.engine negli strumenti di Wren: il motore del thread che li esegue."""
+
+    def __init__(self, postazioni: Postazioni):
+        object.__setattr__(self, "_postazioni", postazioni)
+
+    def __getattr__(self, nome: str):
+        return getattr(self._postazioni.motore(), nome)
+
+
+def rendi_asincroni(server: Any, postazioni: Postazioni, regole: bool = True) -> list[str]:
+    """Gli strumenti di Wren che vanno sul database, eseguiti nei thread delle query.
+
+    FastMCP chiama `fn(**argomenti)` e la attende se `is_async`: la funzione
+    sincrona di Wren resta quella, con lo stesso schema degli argomenti, e gira in
+    Postazioni.esegui. A run_sql si aggiungono le regole delle query."""
+    strumenti = server._tool_manager._tools
+    fatti = []
+    for nome in STRUMENTI_DB:
+        t = strumenti.get(nome)
+        if t is None:
+            continue
+
+        def avvolgi(sincrona: Callable[..., Any]) -> Callable[..., Any]:
+            async def asincrona(**argomenti):
+                descrizione = argomenti.get("sql") or json.dumps(argomenti, ensure_ascii=False, default=str)
+                return await postazioni.esegui(lambda: sincrona(**argomenti), str(descrizione))
+            return asincrona
+
+        t.fn = avvolgi(t.fn)
+        t.is_async = True
+        if nome == "run_sql" and regole:
+            t.description = f"{t.description.rstrip()}\n\n{regole_testo(postazioni.limite_s)}"
+        fatti.append(nome)
+    return fatti
+
+
+def cartella_stato() -> pathlib.Path:
+    return pathlib.Path(os.environ.get("NOEVA_STATO") or tempfile.gettempdir()) / "noeva-stato"
+
+
+def file_stato(server: str, pid: int | None = None) -> pathlib.Path:
+    return cartella_stato() / f"{server}-{pid or os.getpid()}.json"
+
+
+def scrivi_stato(percorso: pathlib.Path, dati: dict) -> None:
+    try:
+        percorso.parent.mkdir(parents=True, exist_ok=True)
+        tmp = percorso.with_suffix(".tmp")
+        tmp.write_text(json.dumps(dati, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, percorso)
+    except OSError:
+        pass  # lo stato serve a --verifica, non al servizio
+
+
+def stato_in_corso(server: str, ora: float | None = None) -> list[dict]:
+    """Gli stati dei servizi vivi di questo server; quelli fermi da tempo si cancellano."""
+    ora = ora or time.time()
+    vivi = []
+    for f in sorted(cartella_stato().glob(f"{server}-*.json")):
+        try:
+            dati = json.loads(f.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        if dati.get("server") != server:
+            continue  # un altro server con un nome che comincia allo stesso modo
+        if ora - float(dati.get("aggiornato") or 0) > STATO_VECCHIO_S:
+            try:
+                f.unlink()
+            except OSError:
+                pass
+            continue
+        vivi.append(dati)
+    return vivi

package/contenuto/lib/mcp-locale/server/noeva_mcp.py

@@ -18,7 +18,14 @@ dashboard su DuckDB come ripiego offline.
     noeva-<id> --sorgente erp       serve MCP su stdio (lo lancia Claude Code)
     noeva-<id> --verifica           controlla driver, password e connessione di
                                     tutte le sorgenti e dice cosa manca: si lancia
-                                    a mano dal PowerShell quando /mcp dice "failed"
+                                    a mano dal PowerShell quando /mcp dice "failed";
+                                    dice anche se il servizio aperto in Claude ha una
+                                    query in corso da troppo tempo
+
+Le query girano in piu' thread, ognuno con la sua connessione, con un tempo
+massimo e l'annullamento sul database (esecuzione.py): una query lenta non ferma
+piu' le altre. In noeva.json, per sorgente: `limite_query_s` (default 120) e
+`connessioni` (default 3; 1 per lo snapshot). NOEVA_LIMITE_QUERY_S forza il limite.
 
 Su stdio lo stdout e' il canale del protocollo: fuori da --verifica qui non si
 stampa niente, i log vanno su stderr.
@@ -31,6 +38,7 @@ import json
 import os
 import pathlib
 import sys
+import time
 
 # Congelato da PyInstaller la cartella e' quella dell'eseguibile; da sorgente,
 # quella sopra server/. NOEVA_DIR la forza (per provare da un'altra macchina).
@@ -53,6 +61,13 @@ class Problema(Exception):
     """Un errore di configurazione da spiegare a chi installa, non uno stack."""
 
 
+def limite_query(s: dict) -> float:
+    """Il tempo massimo di una query, in secondi."""
+    import esecuzione
+
+    return float(os.environ.get("NOEVA_LIMITE_QUERY_S") or s.get("limite_query_s") or esecuzione.LIMITE_S)
+
+
 def configurazione() -> dict:
     p = QUI / "noeva.json"
     if not p.is_file():
@@ -95,11 +110,20 @@ def connessione_mssql(s: dict) -> dict:
         "user": utente or None,
         "password": password or None,
         "driver": driver,
-        "kwargs": {"TrustServerCertificate": "yes", **(s.get("opzioni") or {})},
+        # statement_timeout diventa il timeout della connessione pyodbc: allo
+        # scadere il driver annulla la query sul server (esecuzione.py).
+        "kwargs": {"TrustServerCertificate": "yes", "statement_timeout": str(int(limite_query(s))),
+                   **(s.get("opzioni") or {})},
     }
 
 
 def motore(s: dict):
+    progetto, crea = fabbrica(s)
+    return progetto, crea()
+
+
+def fabbrica(s: dict):
+    """(progetto, crea_motore): il modello si cerca una volta, i motori si fanno uguali."""
     from wren.engine import WrenEngine
 
     import modello_locale
@@ -119,27 +143,36 @@ def motore(s: dict):
             raise Problema(f"nessun .duckdb in {dati}")
         # Il connettore DuckDB attacca in sola lettura ogni .duckdb della
         # cartella, con alias = nome del file: e' il catalogo del modello.
-        eng = WrenEngine(manifest_str=manifest, data_source="duckdb",
-                         connection_info={"url": str(dati), "format": "duckdb"})
-    else:
-        eng = WrenEngine(manifest_str=manifest, data_source="mssql", connection_info=connessione_mssql(s))
-    return progetto, eng
+        return progetto, lambda: WrenEngine(manifest_str=manifest, data_source="duckdb",
+                                            connection_info={"url": str(dati), "format": "duckdb"})
+    info = connessione_mssql(s)
+    return progetto, lambda: WrenEngine(manifest_str=manifest, data_source="mssql", connection_info=info)
 
 
 def servi(conf: dict, nome: str) -> None:
     s = conf["sorgenti"][nome]
-    progetto, eng = motore(s)
+    progetto, crea = fabbrica(s)
+    import esecuzione
+    import modello_locale
     from wren.mcp_server import ServeContext, build_server
 
-    server = build_server(ServeContext(project=progetto, engine=eng, allow_write=False, no_connect=False))
+    limite = limite_query(s)
+    postazioni = esecuzione.Postazioni(
+        crea, connessioni=s.get("connessioni") or (esecuzione.CONNESSIONI if s["tipo"] == "mssql" else 1),
+        limite_s=limite, stato=esecuzione.file_stato(s["server"]), server=s["server"])
+    # Gli strumenti di Wren leggono ctx.engine: il motore del thread che li esegue.
+    server = build_server(ServeContext(project=progetto, engine=esecuzione.MotoreCorrente(postazioni),
+                                       allow_write=False, no_connect=False))
+    esecuzione.rendi_asincroni(server, postazioni, regole=s["tipo"] == "mssql")
     # FastMCP non espone un setter: nome e istruzioni stanno sul server di basso
     # livello, ed e' quello che il client legge all'initialize.
     server._mcp_server.name = s["server"]
     server._mcp_server.instructions = s["istruzioni"]
+    modello_locale.log(f"{s['server']}: {postazioni.connessioni} connessioni, query fermate dopo {int(limite)} s")
     try:
         server.run(transport="stdio")
     finally:
-        eng.close()
+        postazioni.chiudi()
 
 
 def verifica(conf: dict, nomi: list[str]) -> int:
@@ -170,10 +203,48 @@ def verifica(conf: dict, nomi: list[str]) -> int:
                 falliti += 1
                 break
         eng.close()
+        if not query_in_corso(s):
+            falliti += 1
     print("\ntutto a posto" if not falliti else f"\n{falliti} sorgente/i con problemi")
     return 1 if falliti else 0
 
 
+def query_in_corso(s: dict) -> bool:
+    """Le query del servizio aperto in Claude (il file di stato di esecuzione.py).
+
+    Falso se una e' in corso da oltre il tempo massimo: il servizio dovrebbe
+    averla gia' fermata, quindi e' bloccato."""
+    import esecuzione
+
+    vivi = esecuzione.stato_in_corso(s["server"])
+    if not vivi:
+        print("  ..  servizio in Claude: non aperto, o di una versione che non lo dice")
+        return True
+    ora = time.time()
+    bene = True
+    for st in vivi:
+        lavori = st.get("lavori") or []
+        limite = float(st.get("limite_s") or esecuzione.LIMITE_S)
+        if not lavori:
+            print(f"  ok  servizio in Claude (processo {st.get('pid')}): nessuna query in corso")
+            continue
+        in_coda = sum(1 for lv in lavori if lv.get("in_coda"))
+        for lv in lavori:
+            if lv.get("in_coda"):
+                continue
+            durata = ora - float(lv.get("dal") or ora)
+            testo = " ".join(str(lv.get("query") or "").split())[:160]
+            if durata > limite + esecuzione.MARGINE_S + esecuzione.BATTITO_S:
+                bene = False
+                print(f"  NO  query in corso da {int(durata // 60)} min {int(durata % 60)} s, oltre il massimo "
+                      f"di {esecuzione.minuti(limite)}: il servizio e' bloccato, chiudi e riapri Claude. Query: {testo}")
+            else:
+                print(f"  ..  query in corso da {int(durata)} s: {testo}")
+        if in_coda:
+            print(f"  ..  {in_coda} query in coda (connessioni: {st.get('connessioni')})")
+    return bene
+
+
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(prog=pathlib.Path(sys.argv[0]).stem)
     ap.add_argument("--sorgente", help="quale database servire (default: la prima di noeva.json)")

package/contenuto/lib/modello/istruzioni.json

@@ -6,9 +6,12 @@
     "istruzioni.js: i segnaposto sono {progetto} (l'id del registro e di analytics.json) e,",
     "per lo snapshot, {data} (la data del dato). Cio' che e' vero del progetto (cliente,",
     "cosa coprono i dati, dashboard, contatto) sta nella scheda knowledge/rules/00-progetto.md,",
-    "non qui (NW-1261)."
+    "non qui (NW-1261).",
+    "regole_query: come si interroga un database vivo senza bloccarlo (11/11/2026); si",
+    "aggiunge alle istruzioni del vivo e alla scheda 00-progetto, che arriva col modello pubblicato."
   ],
   "nome": "noeva-{progetto}",
   "vivo": "NOEVA Analytics, progetto {progetto}: i dati del cliente dal vivo, in sola lettura. Prima di scrivere SQL leggi get_instructions: la regola 00-progetto dice di chi sono i dati, cosa coprono, dove stanno le dashboard e chi e' il contatto in 4D; le altre regole e describe_model dicono cosa significano i numeri. Valida con dry_run, poi run_sql con un limit; aggrega nel database invece di scaricare righe.",
-  "snapshot": "NOEVA Analytics, progetto {progetto}: SNAPSHOT delle dashboard (dato al {data}), il ripiego offline, non il database vivo. Prima di scrivere SQL leggi get_instructions: la regola 00-snapshot dice quali tabelle esistono e a che data e' il dato, la 00-progetto di chi sono i dati e dove stanno le dashboard. Dillo sempre nella risposta: e' il ripiego offline."
+  "snapshot": "NOEVA Analytics, progetto {progetto}: SNAPSHOT delle dashboard (dato al {data}), il ripiego offline, non il database vivo. Prima di scrivere SQL leggi get_instructions: la regola 00-snapshot dice quali tabelle esistono e a che data e' il dato, la 00-progetto di chi sono i dati e dove stanno le dashboard. Dillo sempre nella risposta: e' il ripiego offline.",
+  "regole_query": "Il database vivo e' quello di produzione, che usa anche il gestionale, e ogni query ha un tempo massimo di 2 minuti: prova la query su un mese, poi sull'anno; una query pesante alla volta, mai in parallelo; aggrega ogni tabella (GROUP BY) prima di unirla alle altre, mai un join riga per riga tra tabelle grandi (per esempio listino e fatture); se una query va in timeout riduci il periodo invece di spezzarla in piu' query in parallelo."
 }

package/contenuto/lib/modello/istruzioni.py

@@ -27,8 +27,13 @@ def nome_server(progetto: str) -> str:
     return _riempi(TESTI["nome"], progetto=progetto)
 
 
+def regole_query() -> str:
+    """Come si interroga un database vivo senza bloccarlo: anche nella scheda 00-progetto."""
+    return TESTI["regole_query"]
+
+
 def istruzioni_vivo(progetto: str) -> str:
-    return _riempi(TESTI["vivo"], progetto=progetto)
+    return _riempi(TESTI["vivo"], progetto=progetto) + " " + regole_query()
 
 
 def istruzioni_snapshot(progetto: str, data: str | None) -> str:

package/contenuto/lib/modello/scheda.py

@@ -21,6 +21,7 @@ Legge, tutti facoltativi tranne analytics.json:
     models/                 quanti modelli
     apps/index.html         il titolo del progetto, che e' quello dell'indice
     apps/*/index.html       le dashboard, col titolo della pagina
+    istruzioni.json         le regole delle query sul vivo (regole_query), se ci sono sorgenti vive
 
 Il registro dei progetti (lib/rilascio/progetti.json) sta nel monorepo di 4D e il
 repository di un cliente non lo vede (il pacchetto non nomina clienti, ADR 0005):
@@ -41,6 +42,11 @@ import sys
 
 import yaml
 
+try:
+    from istruzioni import regole_query
+except (ImportError, OSError):  # un eseguibile costruito senza istruzioni.json: la scheda resta senza
+    regole_query = None
+
 FILE = "00-progetto.md"
 CONTENITORE = "https://analytics.noeva.ai"
 # Le cartelle di apps/ che non sono dashboard: il motore e i moduli di pagina.
@@ -119,6 +125,11 @@ def scheda(sorgente: pathlib.Path, conf: dict | None = None) -> str:
         r.append("- La copertura per sorgente non e' descritta (`cosa` in consegna.yml): la dicono "
                  "le regole e la descrizione dei modelli.")
 
+    if conf.get("sorgenti") and regole_query is not None:
+        # Arriva col modello pubblicato anche ai servizi gia' installati, prima del
+        # loro aggiornamento (11/11/2026: query pesanti in parallelo, connettore fermo).
+        r += ["", "## Le query sul database vivo", "", regole_query()]
+
     r += ["", "## Le dashboard", "",
           "Dietro il login NOEVA: le apre chi ha il progetto nel suo workspace.", "",
           f"- Indice: {base}"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noeva/analytics-core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Gli strumenti di un progetto NOEVA Analytics nel suo repository: moduli di pagina, snapshot, verifica dello standard e kit dell'agente (ADR 0005).",
   "type": "module",
   "bin": {