Setup verificabile degli agenti

In breve

Un setup è attendibile quando chiude un ciclo: dichiara, applica, verifica, rimuove. L’installazione di un binario è soltanto uno degli effetti possibili. Configurazione, launcher, plugin e variabili richiedono ciascuno una prova e una regola di proprietà. Se la rimozione non sa distinguere ciò che ha creato da ciò che esisteva già, il setup non è reversibile e non dovrebbe gestire quell’artefatto.

Il ciclo operativo

Fase	Input	Evidenza attesa	Fallimento utile
Dichiara	valori, prerequisiti, artefatti gestiti	contratto leggibile e validato	parametro mancante o incompatibile
Applica	contratto e stato precedente	elenco degli effetti creati o aggiornati	nessuna modifica parziale nascosta
Verifica	stesso resolver del launcher	capacità osservata sul canale reale	fase e causa distinte
Rimuove	inventario di proprietà	soli effetti posseduti assenti	artefatto estraneo conservato

Il ciclo completo è il test di replicabilità: rimozione, verifica dello stato pulito, applicazione, seconda verifica. “Pulito” non significa macchina spogliata; significa che nessun effetto posseduto dal toolkit è rimasto applicato. Un binario o una preferenza preesistenti devono sopravvivere. La precedenza dei parametri definisce come tutte le fasi ottengono gli stessi valori.

Proprietà prima dell’idempotenza

L’idempotenza non è “il secondo run non stampa errori”. È l’invariante per cui due applicazioni consecutive producono lo stesso stato gestito. Per provarla serve un inventario persistente che registri almeno: identità logica dell’artefatto, stato precedente, modifica effettuata e proprietà. Il registro va scritto atomicamente; se manca o è illeggibile, il comportamento prudente è considerare l’artefatto non posseduto.

Un caso reale ha mostrato il rischio opposto: un setup adottava nella propria cache un eseguibile già presente, ma non ne registrava la provenienza. La rimozione successiva trattava quella copia come propria e rendeva indisponibile il comando dell’utente. Il rimedio non è stato un altro controllo sul percorso, bensì ownership esplicita e ripristino del valore precedente.

Probe minimo, non inventario

Ogni effetto ha un’asserzione diversa. Un file richiede firma o struttura valida; una configurazione richiede il valore effettivamente letto; un bridge richiede un handshake; un worker richiede una risposta minima. Il probe deve usare dati sintetici, una directory temporanea dedicata e nessun transcript di sessione.

preflight  -> prerequisiti e contratto validi
apply      -> effetti registrati, nessun duplicato
probe      -> stesso entry point del lavoro, risposta attesa
remove     -> solo effetti posseduti rimossi
verify     -> stato gestito pulito, preesistenze conservate

In un secondo incidente, il ripristino conservava la cartella visibile dell’eseguibile ma non le risorse companion del pacchetto. Il comando di versione funzionava; i tool di shell no. Il controllo corretto è diventato un probe di capacità sul percorso canonico, non Test-Path. È il motivo per cui verificare il canale eseguito è parte del setup e non un controllo successivo facoltativo.

La documentazione di Reproducible Builds offre principi utili su input e ambiente registrati; qui li si estende allo stato operativo e alla reversibilità, che non sono garantiti dalla sola riproducibilità dell’output.

Limiti

Il ciclo non rende portabili identità, autorizzazioni, rete o servizi esterni. Un probe riuscito prova una capacità circoscritta nel tempo. Modifiche manuali, processi che conservano un ambiente precedente e aggiornamenti del vendor possono invalidare lo stato subito dopo. Quando proprietà o stato precedente sono incerti, la procedura deve fermarsi o conservare l’artefatto: non dedurre una macchina ideale.

Voci correlate

• Precedenza dei parametri
• Verificare il canale eseguito
• Portabilità degli agenti

Fonti

• The Twelve-Factor App: Config, riferimento generale per separare configurazione e codice.
• Reproducible Builds, riferimento primario per output deterministici, ambienti di build registrati e verifica; non dimostra ownership o idempotenza di un setup di agenti.