1. Scopo e confini

Questo documento definisce cosa è un executor, come è fatto, come si autentica, come si isola, come nasce, come muore. È il primo dei tre doc canonici introdotti dal Dialogo sugli executor e la memoria distribuita (24 aprile 2026), insieme a mnest e mnestoma. Sostituisce il vecchio neuron.html: tecnicamente è lo stesso oggetto, ma il nome «neurone» portava una metafora biologica che diventava ingombrante quando si scendeva nel dettaglio implementativo. Executor è più preciso: è codice eseguibile.

Confini

Il documento copre:

• il contratto strutturale di un executor (header, manifest, firma, profilo, codice);
• la macchina a stati del suo ciclo di vita;
• il flusso d'esecuzione visto dal lato gateway;
• la pipeline di sintesi che porta un proto-mnest a diventare un executor.

Non copre, e demanda altrove:

• la struttura dei mnest e del mnestoma (vedi i doc dedicati);
• le politiche di Vaglio (vedi vaglio.html, da riscrivere);
• il profilo di isolamento tecnico (vedi sandbox.html, da riscrivere);
• il workspace (vedi workspace.html, da riscrivere).

2. Cos'è un executor

Un executor è un'unità di codice che Metnos può eseguire come passo del proprio ragionamento. Una funzione con un contratto pubblico, un'identità firmata, un profilo di isolamento, un manifest che descrive cosa fa e a quali risorse accede. Nient'altro. Non è un agente, non è un microservizio, non è un plugin: è un piccolo blocco eseguibile, sotto firma del progetto.

Tre categorie, una stessa anatomia esterna

La distinzione fra seed e sintetizzati è storica, non strutturale: un seed è generato manualmente prima del primo avvio, un sintetizzato è generato automaticamente in vita. Una volta firmati, il gateway li tratta esattamente nello stesso modo.

I builtin sono diversi: condividono il contratto esterno con seed e sintetizzati (stesso run(args, ctx) -> dict, stesso audit, stesso schema I/O), ma non hanno manifest.toml separato, non hanno profile.lock per istanza, non passano per la pipeline di sintesi. Vivono nei sorgenti di Metnos e vengono firmati come parte della release. Il synt non può mai generare un builtin (cap. 7): sono fondazionali, non sintetizzabili.

3. Anatomia: i sei artefatti

Un executor vive sotto workspace/executors/<nome>/. La directory contiene sei artefatti, in questo ordine di lettura:

4. Identità: manifest, firma, versione

Il manifest

Il manifest è il documento di identità di un executor. Esempio per fs_read:

[executor]
name        = "fs_read"
version     = "1.0.0"
created_at  = 2026-04-25T08:12:00Z
created_by  = "seed"               # oppure: "synt:<run_id>"
summary     = "Leggi un file dal workspace e ritornane il contenuto."

[contract]
input_schema  = "schema.json#/definitions/Input"
output_schema = "schema.json#/definitions/Output"
error_classes = ["NotFound", "PermissionDenied", "TooLarge"]
idempotent    = true
side_effects  = false

[sandbox]
profile = "fs-read-workspace"      # vedi sandbox.html
hash    = "blake3:abc123..."       # impronta del profilo

[audit]
trace_topic = "executor.fs_read"

Tre campi sono normativi:

• name e version formano l'identità che il gateway usa per risolvere ogni invocazione. name è immutabile per tutta la vita dell'executor; version segue semver con una regola dura: ogni cambiamento al codice o al contratto incrementa il major.
• contract è lo schema d'uso. Non si può aggiungere o rimuovere un campo d'ingresso senza incrementare la versione.
• sandbox.hash aggancia l'identità al profilo. Cambiare profilo significa cambiare identità.

La firma

Il file manifest.sig contiene la firma Ed25519 (curva 25519, chiave privata in ~/.config/metnos/keys/ con permessi 600, non versionata) sui seguenti byte concatenati:

blake3(manifest.toml) || blake3(main.py) || blake3(schema.json) || profile.lock

Il loader del gateway, all'avvio e a ogni richiesta, verifica:

1. la firma è valida con la chiave pubblica del progetto;
2. i quattro hash corrispondono ai file su disco;
3. il manifest è semanticamente coerente (schema valido, profilo esistente).

Se anche un solo controllo fallisce, l'executor è rifiutato. Non viene caricato, non viene invocato, non viene cancellato: viene messo in quarantena (cap. 6) e segnalato all'utente.

Versionamento

Una versione di executor non si modifica mai «sul posto». Per fare una modifica si crea una nuova versione (es. 1.0.0 → 2.0.0) con la sua firma. Il gateway può tenere caricate più versioni in parallelo finché ce ne sono mnest che le citano (vedi mnest.html). La promozione di una nuova versione a default è un atto esplicito e firmato: viene scritto in workspace/executors/<nome>/CURRENT.

5. Profilo di sandbox

Il profilo è il punto in cui l'identità di un executor incontra la safety del perimetro (Architettura cap. 5). La sezione è più lunga del normale perché due distinzioni vanno fissate bene, e la domanda «l'executor può leggere fuori dal sandbox?» deve avere una risposta operativamente chiara, non slogan.

5.1 Profilo dichiarato vs sandbox applicata

Sono due cose diverse, accoppiate, che spesso vengono confuse:

I due strati sono tenuti in sincrono dal profile lock descritto al cap. 3: l'hash del profilo concreto, calcolato al momento della firma, è congelato in profile.lock. A ogni invocazione, il loader del gateway ricalcola l'hash della sandbox che sta per applicare e la confronta con il lock; se diverge, l'invocazione fallisce. Così un cambio silente del profilo — di chiunque — viene intercettato.

5.2 Le cinque dimensioni del profilo

5.3 Può leggere fuori dal sandbox? No, mai. Perché.

Risposta breve: no. Quello che il profilo non concede, il processo dell'executor non lo vede e non lo può vedere. Non è una raccomandazione di stile, è una limitazione del kernel.

Risposta lunga, in tre passaggi:

1. Mount namespace. bubblewrap apre il processo in un mount namespace privato in cui sono visibili solo i path elencati nel profilo (montati read-only o read-write a seconda del campo). Tutto il resto del filesystem semplicemente non esiste dal punto di vista del processo. Una open('/etc/passwd') ritorna ENOENT (file non trovato), come se il file non ci fosse mai stato.
2. Landlock. Sopra al mount namespace, il kernel applica una policy landlock che restringe ulteriormente: anche path montati read-only non possono essere aperti per scrittura, anche path scrivibili non possono essere aperti con flag pericolosi. Una violazione restituisce EACCES.
3. Seccomp. Le syscall di rete sono filtrate da seccomp: l'executor che non ha rete in profilo riceve EPERM su connect(). L'executor che ha rete su allowlist passa per un proxy locale che blocca tutto fuori dalla allowlist.

È difesa in profondità: il primo livello (mount namespace) già basterebbe per i percorsi non elencati; il secondo (landlock) gestisce le sfumature di scrittura/lettura; il terzo (seccomp) chiude il lato di rete. Tre meccanismi indipendenti del kernel, configurati dal profilo. Aggirarli richiederebbe un bug del kernel, non un bug dell'executor.

5.4 Esempio operativo: fs_read chiamato male

Supponiamo che il gateway riceva la richiesta: fs_read({path: "/etc/passwd"}). L'executor fs_read ha profilo fs-read-workspace che concede sola lettura su workspace/. Cosa succede?

Il design corretto è che l'errore venga intercettato al passo 1 (policy-time), non al passo 2 o 3 (kernel-time): è più veloce, più informativo per il chiamante, e non lascia tracce nel sandbox. I passi 2 e 3 sono la rete di sicurezza che esiste se il primo dovesse fallire per un bug nostro.

5.5 Forbidden paths del nucleo: sopra al profilo

Esistono percorsi che nessun profilo può concedere, nemmeno se il manifest li dichiarasse. Sono i forbidden paths del nucleo, hard-coded nel codice del gateway, irriducibili, modificabili solo per rito (modifica del codice, revisione, rilascio):

• ~/.ssh/, ~/.gnupg/ — chiavi crittografiche dell'utente;
• ~/.config/myclaw/, ~/.config/metnos/ — cassaforte dei segreti del progetto;
• workspace/.audit/ — il registro append-only delle azioni; nemmeno modificabile dall'audit log writer stesso, che apre il file in modalità append via syscall dedicata;
• aree di sistema (/etc/, /proc/, /sys/, eccezioni esplicite per file innocui letti dal runtime Python).

La differenza concettuale: il profilo è modulazione dichiarata per executor; i forbidden paths del nucleo sono divieti universali del sistema. Vivono su due piani diversi dell'asse 2 della safety del perimetro (Architettura cap. 5): il guscio modulabile (profili) e il nucleo duro (forbidden paths). Il livello di autonomy Full può allargare il guscio, mai il nucleo.

5.6 Posso derogare? Path fuori dal workspace, e il caso «riordina le foto»

Sì. Niente nel design vieta a un profilo di dichiarare path fuori da workspace/. Il profilo è una dichiarazione esplicita: si può dichiarare ~/Immagini/, ~/Documenti/lavoro/, una cartella di rete montata, una partizione di backup. Quello che il profilo dichiara, la sandbox concede; quello che il nucleo vieta resta vietato comunque (cap. 5.5).

La deroga, però, è un atto pesato. Ha tre vincoli:

1. È esplicita. Va dichiarata nel manifest, non implicita. Un revisore che legge il manifest deve vedere subito che questo executor tocca ~/Immagini/ e non solo il workspace.
2. È firmata. Il profilo ampliato cambia l'hash di profile.lock; cambiare profilo significa cambiare versione, e cambiare versione richiede una nuova firma e una nuova approvazione. Non si può allargare il sandbox di nascosto.
3. Resta sotto il nucleo. Anche un profilo che dichiara ~/ letto+scritto non può accedere a ~/.ssh/, ~/.gnupg/, ~/.config/myclaw/: i forbidden paths del nucleo (cap. 5.5) sono mascherati dalla mount namespace anche dentro un profilo «ampio».

Caso d'uso: riordina le foto

È un caso reale. Le foto vivono in ~/Immagini/ (sul server) o in C:\Users\Roberto\Pictures\ (sul laptop). Le due situazioni sono distinte e si risolvono in modo distinto.

6. Lifecycle: seed, attivo, fuso, quarantena, archiviato

7. Sintesi (synt): da proto-mnest a executor

Il synt è il processo che fa nascere nuovi executor quando l'uso lo richiede. La fonte d'innesco è un proto-mnest ricorrente: una traccia di desiderio non soddisfatto («l'output di A doveva andare a B che non esiste ancora») che si ripete più volte nello stesso mese.

La pipeline ha sette stadi. Ogni stadio può sospendere e chiedere all'utente.

La separazione è netta: il synt propone, l'utente approva. Niente sintesi senza filtro umano; questo è il terzo dei sei principi (cap. 14 dell'Architettura). Il dettaglio della pipeline vive in synthesizer.html (da riscrivere).

7.1 La cascata: comporre prima, generare poi

La pipeline a sette stadi descritta sopra è il braccio della generazione: produce un executor nuovo. Ma non è il primo strumento che il synt usa quando un proto-mnest ricorre. La sequenza canonica è una cascata:

I tre passi introvertivi (fondere, generalizzare, specializzare) non hanno ancora un doc dedicato; la collocazione naturale è un capitolo aggiuntivo dentro il futuro synt riscritto, oppure un nuovo doc consolidator.html. Decisione aperta.

8. Esecuzione: chiamata dal gateway

Il flusso di un'invocazione dal gateway a un executor passa attraverso otto passi. Ne diamo qui la sequenza alta; il dettaglio dei passi intermedi (Policy, Vaglio, sandbox) vive nei rispettivi doc, da riscrivere.

1. Il gateway riceve un'azione: chiamata di executor X con input {...}.
2. Risolve X in workspace/executors/X/CURRENT; se non c'è CURRENT o è in quarantena, fallisce.
3. Verifica firma e profilo lock. Se rotta, quarantena e fallimento.
4. Valida l'input contro schema.json. Se non valido, fallimento con errore strutturato.
5. Apre il sandbox col profilo dichiarato. Le quattro Leggi entrano qui come ulteriore filtro.
6. Esegue run(args, ctx). Tempo limite, memoria limite, rete limitata.
7. Valida l'output contro schema.json. Se non valido, fallimento.
8. Scrive nell'audit log: chi ha chiamato, con cosa, quanto è durato, cosa ha restituito (in forma normalizzata, con eventuali segreti redatti).

Lungo il flusso, il gateway aggiorna due strutture:

• il turn record della richiesta, che diventa parte dell'execution trace;
• il mnestoma, in particolare il mnest che lega il chiamante a questo executor. Vedi mnest.html.

9. Audit e osservabilità

Ogni invocazione produce una riga JSONL in workspace/.audit/executors/YYYY-MM-DD.jsonl:

{
  "ts":         "2026-04-25T08:14:33.881Z",
  "trace_id":   "01HW...",
  "turn_id":    "01HX...",
  "executor":   "fs_read",
  "version":   "1.0.0",
  "caller":     {"kind": "user", "sender": "roberto", "channel": "telegram"},
  "input":      {"path": "workspace/notes/giornaliero.md"},
  "output":     {"size": 4231, "sha":"blake3:..."},
  "duration_ms": 18,
  "exit":       "ok"
}

Tre invarianti che il loader e il runtime garantiscono:

1. append-only: il file di audit non si modifica mai; gli sbagli si annotano scrivendo una riga successiva di rettifica.
2. autodescrittivo: ogni riga contiene tutto ciò che serve per ricostruire l'invocazione, senza dover incrociare con altre fonti.
3. redatto: i segreti riconosciuti (chiavi API, password, token) sono sostituiti da un placeholder con il loro hash, mai dal valore in chiaro.

10. Esempi: tre seed e un builtin

Tre seed di esempio

fs_read

Legge un file dal workspace. Profilo: filesystem letto-solo su workspace/; nessuna shell, nessuna rete; durata max 2 secondi; output max 4 MB. Errori: NotFound, PermissionDenied, TooLarge. Idempotente.

web_fetch

Scarica una pagina web e la restituisce come testo o markdown. Profilo: nessun filesystem, rete in uscita su HTTP/HTTPS verso domini in allowlist (configurabile per istanza); durata max 15 secondi; output max 2 MB. Errori: DnsError, Timeout, Forbidden, TooLarge. Idempotente.

telegram_send

Invia un messaggio al chat fidato dell'utente. Profilo: nessun filesystem, rete in uscita solo verso api.telegram.org; durata max 5 secondi. Effetti collaterali: sì (manda un messaggio). Errori: RateLimited, Unauthorized, Network. Non idempotente: due chiamate con lo stesso input mandano due messaggi.

Un builtin di esempio: scheduler

Lo scheduler è il primo (e per ora unico) executor builtin proposto: invoca un altro executor (o catena) a un ritmo definito. È il meccanismo che fa esistere «richieste con schedulazione» senza inventare una categoria di design separata. Sostituisce l'idea sbagliata di «routine concordate» come oggetto a parte.

Contratto

Output: {schedule_id: ULID, next_fire: timestamp}.

Operazioni gemelle, anch'esse builtin: scheduler.list (elenca le schedule attive), scheduler.cancel (chiude una schedule), scheduler.modify (cambia ritmo, expiry, count o canale). Ogni modifica passa per il gate umano se cambia ritmo o target_executor.

Profilo (dichiarato in codice, non in manifest)

• Filesystem: lettura/scrittura su workspace/.runtime/scheduler.sqlite (lo schedule store).
• Rete: nessuna direttamente; può però invocare executor che usano la rete (autenticati separatamente).
• Capability speciali: system:scheduler (accesso al loop async del gateway, non concedibile a nessun seed o sintetizzato).
• Idempotente: la creazione di una schedule sì (stessa configurazione → stessa schedule_id, return identico). I firing no, dipendono dal target.

Audit

Ogni firing emette una riga JSONL come ogni altra invocazione executor, con caller = {"kind": "scheduler", "schedule_id": "…"}. La storia di una schedule è ricostruibile per schedule_id: creazione, modifiche, ogni firing, eventuale chiusura.

Lo scheduler è il primo builtin perché risolve un caso ricorrente (presidio di una casella di posta, riassunto giornaliero, controlli periodici) con un meccanismo che si compone naturalmente con la cascata di synt: una schedule reiterata diventa candidata di fusione (synt cap. 5.1) in un singolo executor che incorpora la catena.

11. Rinomina: neurone → executor

La microprogettazione precedente usava il termine neurone (neuron.html, ora deprecato e marcato untrusted). Il Dialogo sugli executor e la memoria distribuita ha rinominato il termine in executor per due ragioni:

1. Precisione. Un neurone biologico non è codice eseguibile sotto firma, né ha un manifest, né un profilo di sandbox. La metafora aiutava il primo brainstorm ma diventava ingombrante nei doc tecnici.
2. Allineamento con l'esecuzione. Il gateway parla con executor: codice eseguibile invocato per produrre un risultato. Il nome ricorda quel verbo.

Il termine biologico continua a funzionare bene per descrivere il mnestoma emergente come un grafo: questo è un altro livello di metafora (il grafo come tessuto), su cui torneremo nei doc dedicati.

12. Executor remoti: stesso contratto, processo altrove

La topologia (Architettura cap. 4) dichiara che alcuni executor, in futuro, non gireranno sul metnos-server ma sulle macchine dell'utente: il laptop in primo luogo. Questo capitolo dice cosa cambia, in concreto, per il microdesign dell'executor quando il processo non vive più sul server.

Cosa NON cambia

Il contratto di un executor remoto è identico a quello di un executor locale. Stessa anatomia (cap. 3): manifest TOML, firma Ed25519, codice main.py, schema I/O, test di nascita, profile lock. Stessa pipeline di sintesi (cap. 7). Stessa identità gateway-side (cap. 4). Stesso lifecycle (cap. 6). Stesso audit log centrale, su metnos-server (cap. 9): chi chiama un executor remoto e cosa riceve indietro è tracciato esattamente come per uno locale.

Il manifest dell'executor remoto vive comunque sul server metnos-server, sotto workspace/executors/<nome>/. Il server è la fonte canonica del «chi» e del «cosa». Sul laptop vive solo l'esecuzione: un piccolo processo confinato, lanciato e supervisionato dal lato server attraverso il canale Headscale (vedi Architettura cap. 4).

Cosa cambia, e perché

Esempio: photo_organize sul laptop

L'esempio canonico del cap. 5.6: riordinare un archivio fotografico di diecimila file che vivono in C:\Users\Roberto\Pictures\. Sincronizzarli sul server, riordinarli, risincronizzarli indietro implica gigabyte di traffico, doppia occupazione disco, finestre temporali in cui lo stesso file esiste in due stati su due macchine. Una rename sul posto, eseguita direttamente dal laptop, risolve in un secondo. Però il processo che esegue quella rename deve essere fidato e tracciato come ogni altro executor di Metnos.

Il flusso, in concreto:

1. Sintesi. Il synt (cap. 7) propone photo_organize con manifest che dichiara: input = lista di regole di sort, output = numero di file riordinati, profilo = read-write su C:\Users\Roberto\Pictures\ (escluse sottocartelle riservate), nessuna shell, nessuna rete. Roberto approva, il manifest viene firmato sul server.
2. Pairing del dispositivo. Roberto, da Telegram, conferma che il laptop «Acme-15» può eseguire executor remoti. La cerimonia genera una chiave pairing che vive nel mnestoma e nel piccolo runtime sul laptop.
3. Distribuzione. Il gateway invia il binario firmato di photo_organize al laptop, che lo verifica contro il manifest e lo scrive in cache locale.
4. Invocazione. Roberto dice «riordina le foto del 2024 per data di scatto». Il gateway prepara una chiamata con trace_id univoco, scrive su metnos-server il manifest del «prima» (lista dei path che verranno rinominati, hash), poi invia la chiamata al laptop via Headscale + mTLS.
5. Esecuzione locale. Il piccolo runtime sul laptop verifica autenticità e firma, apre il sandbox debole (AppContainer/permessi NTFS) col profilo dichiarato, esegue la rename, ritorna l'esito.
6. Audit. Due righe JSONL: una su metnos-server (chi ha chiamato, quando, esito), una sul laptop (lista dei path effettivamente toccati, hash dopo). Correlati per trace_id.
7. Eventuale annullamento. Se Roberto si pente, il gateway legge il manifest del «prima» e invia al laptop la chiamata inversa. La reversibilità è preservata.

13. Domande aperte

1. Chiave di firma. La chiave Ed25519 vive sotto ~/.config/metnos/keys/. Quando un nuovo dispositivo deve poter firmare nuovi executor (es. il laptop di Roberto in viaggio), come si autorizza? Pairing del dispositivo (cap. 4 dell'Architettura) + delega a tempo? Aperta.
2. Condivisione fra istanze. Se in futuro Metnos diventa multi-istanza (executor remoti su un secondo dispositivo), come si propaga la firma di un executor nuovo? Replica con verifica sul lato remoto? Aperta.
3. Versioni in sospeso. Una nuova versione di un executor in fase di test convive con la vecchia. Per quanto? La promozione è manuale o ha una soglia automatica? Aperta, vedi roadmap fase 4.
4. Manifest validation. Useremo un parser TOML che esponga errori posizionali? Esiste un test di compatibilità col toolchain? Aperta.

Metnos — executor microprogettazione v1.1 — 2026-04-24
Doc canonico nuovo. Sostituisce neuron.html (deprecato).