Microprogettazione

Questa pagina è la guida d’ingresso alla microprogettazione di Metnos. Non descrive il sistema dall’alto — quello lo fa l’Architettura — Introduzione — ma ne mostra i pezzi: come si chiamano, cosa fanno, come si parlano fra loro. Procediamo dal generale al particolare, fissando i termini prima di usarli.

1. Che cos’è la microprogettazione

L’architettura di Metnos vive su due piani. Il piano alto — chiamato Livello 1 — descrive il sistema nel suo insieme: i quattro strati, gli organi, le leggi, i fini. Lo trovate nel file Metnos_Architettura_Intro_v1.html.

Questa cartella è il piano basso, il Livello 2: un documento HTML per ogni componente, con il dettaglio sufficiente a scriverne il codice senza inventare nulla. Le scelte qui non sono opinioni — sono contratti: schema dei dati, firme delle funzioni, flag di sandbox, condizioni di errore. Quando il codice e il documento divergono, vince il documento e il codice si adegua, oppure il documento viene corretto subito (mai «dopo»).

La regola di vita è semplice: nessun componente viene implementato prima che il suo HTML esista, sia approvato e parli la stessa lingua del codice già in casa.

2. Le quattro parole da conoscere prima

Tutto Metnos gira intorno a quattro nomi. Definirli adesso vi risparmia mezz’ora di confusione fra trenta righe.

executor

Una capacità eseguibile: un piccolo programma che fa una cosa sola e bene (leggere file, mandare una mail, calcolare un hash, tradurre un OCR, scoprire URL nuovi su un sito). Ogni executor accetta liste in ingresso e produce liste in uscita; ha un manifest che lo descrive, una firma Ed25519 che lo autentica e un profilo di sandbox che lo confina. Il pool corrente conta 79 executor fra scritti a mano in /opt/metnos/executors/ e sintetizzati al volo in ~/.local/share/metnos/executors/, più quelli importati da skill esterne.

mnest

Il filo che collega due executor quando sono stati attivati insieme dal pianificatore. Non è un puntatore di codice, è una traccia: nasce dal contesto, si rinforza con la ripetizione, decade se non viene riusato.

mnestoma

Il grafo emergente di tutti i mnest. È la memoria associativa del sistema: vive su SQLite, viene curata da un processo notturno (ager) e fornisce al pianificatore l’intuizione di «quale executor di solito segue quale». La controparte inglese del termine è mnestome.

agent runtime

Il motore che orchestra il tutto: riceve la richiesta dell’utente, la spezza in passi, sceglie gli executor, li lancia in sandbox, raccoglie le osservazioni, decide il passo dopo. Implementa il loop ReAct con tool-use nativo (LLM locale Qwen 3.6 35B-A3B) e si appoggia agli altri componenti per le decisioni difficili (Vaglio per la sicurezza, Synt per le capacità mancanti, Telos per i fini).

3. La mappa dei componenti

Sono ventuno componenti documentati. Lo schema sotto li raggruppa per ruolo: il bordo nero spesso è il motore centrale, le forme verdi i «servizi» che il motore consulta, le forme azzurre i «tessuti» che memorizzano lo stato, le forme color bronzo gli organi periferici verso l’utente e verso l’ambiente. Le frecce indicano chi chiama chi.

Tre osservazioni utili per leggere lo schema.

1. Il telos sta sopra a tutto: non è un servizio che si chiama, è un’orientazione. Il runtime pesa le alternative anche in funzione dei fini dichiarati nell’omonimo file del workspace.
2. Il vaglio è sempre prima dell’esecuzione, mai dopo. Una volta che un executor è partito non si torna indietro in modo gratuito: l’undo esiste, ma costa storia e blob di backup.
3. Il pool di executor è aperto: il synt può comporne di nuovi mettendo in fila quelli esistenti, oppure (se non basta) generandone uno ex novo, con firma e installazione automatica.

4. Come scorre una richiesta dell’utente

Per fissare la mappa, seguiamo una richiesta semplice dall’ingresso fino alla risposta: «sposta in ~/Archivio/2026 i PDF di fatture arrivati questa settimana».

1. Channel. Telegram riceve il messaggio dell’utente. Il daemon controlla che il mittente sia stato pairato con un livello d’autorizzazione sufficiente; in caso contrario il messaggio viene scartato senza eco. Pairing significa «canale + sender ID riconosciuto»: si ottiene rispondendo a un codice Ed25519 firmato con TTL.
2. Agent runtime — pianificazione. Il runtime estrae l’intent (verbo canonico: move; oggetto: files; criterio: PDF allegati a fatture in finestra «ultima settimana»), interroga il prefilter per ridurre il catalogo agli executor pertinenti e prepara il primo passo del loop ReAct.
3. Vaglio — guardia + giudice. Prima di lanciare l’executor il Vaglio controlla due cose: che il percorso non sia vietato (forbidden paths), che il comando shell non sia irrecuperabile (rm -rf e simili). Per le operazioni che cadono in zona grigia, il giudice rule-based assegna un punteggio e, se sopra soglia, chiede una conferma all’utente tramite carta a 3 righe (cosa/dove/perché).
4. Sandbox + executor. Il runtime invoca read_messages dentro bwrap con i flag derivati dal manifest. L’output torna come lista di entries; ogni entry è un dizionario con il path del PDF e i metadati.
5. Pipe. Il passo successivo è move_files; riceve la lista del passo precedente con from_step: N. La verità sui dati vive nello scratchpad: il pianificatore non vede l’intera lista, ne vede una vista sintetica che gli basta per decidere.
6. Mnest + mnestoma. La coppia read_messages → move_files rinforza una traccia esistente nel grafo. Se non esiste, viene creata. L’ager notturno farà manutenzione: decadimento, fusioni, scarti.
7. Risposta. Il runtime restituisce all’utente, via Telegram, il numero di file spostati e il primo motivo di scarto se qualcosa è stato escluso. La final_answer include il marker di troncamento se la lista di partenza era stata limitata da un cap.

5. I ventuno documenti canonici

Sotto, i ventuno documenti raggruppati per ruolo. Tutti hanno la controparte inglese in /en/architecture/.

6. Vocabolario e primitive

Il vocabolario chiuso conta 23 azioni (read, write, move, delete, create, find, list, filter, sort, group, classify, get, set, send, describe, render, extract, compress, compute, compare, change, order, share) e 22 oggetti (files, dirs, packages, messages, events, calendars, contacts, places, processes, urls, numbers, images, signatures, texts, proposals, inputs, credentials, entries, persons, tasks, issues, pulls). I qualifier sono divisi in quattro famiglie: formato (codifica del dato), modalità (come agisce l’executor), criterio di sicurezza, provider (per indicare un backend diverso da quello predefinito, ad esempio _google_workspace). Tutto centralizzato in runtime/vocab.py.

Le liste di entries che il turno produce passo per passo si manipolano con tre primitive. filter_entries riduce una lista applicando un predicato a un campo (where_starts_with, where_contains, where_glob, where_regex). filter_lists opera fra due liste: intersezione, unione, differenza, differenza simmetrica e sovrapposizione temporale. compute_entries calcola un numero a partire da una lista (somma, media, minimo, massimo, conteggio). Esempio reale: la domanda «c’è un appuntamento HLT che si sovrappone a uno MNM nei prossimi tre mesi?» viene risolta in sei passi: read_events → due filter_entries (uno per HLT, uno per MNM) → filter_lists(op=overlap) → risposta finale.

Il pool di executor conta 79 unità fra scritti a mano e sintetizzati, più gli executor importati da skill esterne (Google Workspace, ecc.). Verbi-produttori ortogonali a 5 (find per pattern, get per id/stato, read per blob da sorgente, list per container, filter per riduzione).

7. Convenzioni di scrittura

Ogni file di microprogettazione segue lo stesso template dell’Architettura — Introduzione:

• palette navy / sage / bronze; CSS inline, niente dipendenze esterne;
• title-page, indice numerato, capitoli con id stabili;
• almeno una figura SVG inline (mai PNG: i diagrammi devono restare ricercabili e leggibili in PDF stampato);
• una sezione Contratto (Protocol + condizioni di errore), una Implementazioni, una Test di conformità;
• sticky nav in alto con breadcrumb;
• le regole prescrittive ai LLM seguono il pattern DEVI / NON DEVI / OK / ERRORE, quattro righe massimo;
• nessun anglicismo gratuito quando esiste una resa italiana piana (no peer, trigger, plumbing, gate);
• nessun nome proprio di terzi: solo «Roberto» o generici (guest, ospite, familiare invitato);
• etichette di alternative come (a)/(b)/(c), mai con lettere greche.

Continua a leggere