Chiedi a Metnos con una richiesta come quella di questo esempio: «Spiegami quali controlli si applicano se chiedo di leggere un file e quali se chiedo di modificarlo». La risposta deve distinguere i controlli attivi del runtime dalla matrice dichiarativa descritta in questa pagina.

runtime/policy.py offre un registro canonico, una matrice deterministica dei livelli di autonomia e un archivio di concessioni circoscritte a un obiettivo. Queste API sono disponibili e ispezionabili, ma non costituiscono ancora il controllo generale del percorso ordinario di esecuzione. Le autorizzazioni effettive del runtime sono descritte nei documenti dei componenti che le applicano.

1. Cos'è policy

Il modulo policy descrive un possibile esito di autorizzazione per una tripla composta da livello di autonomia, capacità e obiettivo. L'esito può essere consentito, negato oppure approvazione richiesta. È un modello deterministico disponibile nel codice; non va confuso con un controllo già applicato a ogni executor.

Il modello distingue tre responsabilità, affidate a componenti diversi:

• il modulo policy calcola un esito strutturato a partire dai dati che gli vengono forniti;
• il vaglio decide il senso — ha senso farlo, dato il contesto della richiesta?
• la sandbox applica l'isolamento disponibile e dichiara quando deve operare in modalità degradata.

Questa separazione è il disegno del sottosistema, non una dichiarazione sull'ordine del percorso attuale. Nel codice corrente il registro viene usato per convalidare le capacità dichiarate dai manifest; la chiamata generale a effective_outcome prima di ogni esecuzione non è ancora presente.

Contratto dichiarativo. I manifest attivi dichiarano capacità appartenenti al registro canonico. I controlli effettivi restano distribuiti fra convalida del manifest, vaglio, dialoghi di approvazione, sandbox e regole specifiche del dispatcher; questa pagina non li attribuisce tutti a policy.py.

2. Registro delle capacità

Il registro è il dizionario chiuso delle capacità riconosciute dal validatore dei manifest. Le voci canoniche sono definite in runtime/policy.py:CAPABILITY_REGISTRY. Ogni voce è un CapabilitySpec con quattro attributi:

• name — il nome canonico (formato famiglia:modo, es. fs:read);
• critical — True se l'azione è irreversibile o ad alta posta in gioco (write, send, exec);
• default_approval — classe usata per costruire la matrice: none, per_target o always;
• target_kind — tipologia del bersaglio: path_glob, host, exact, none.

La tabella seguente mostra un gruppo rappresentativo. Il registro nel codice e l'uscita del comando registry sono le fonti complete e aggiornate.

Il registro è chiuso: record_grant rifiuta una capacità che non vi appartiene. Aggiungerne una significa modificare il registro nel codice e convalidare i manifest — non esiste una registrazione dinamica durante l'esecuzione. Il vocabolario delle azioni è quindi un contratto controllato.

provider:access usa come bersaglio esatto il binding della skill. Una clausola when nel manifest può restringerla a un backend della singola invocazione; la policy non ricava mai questo permesso dal nome dell'executor o da un valore libero del piano.

2.1 Come leggere il registro

Il registro comprende letture, scritture, accessi a fornitori esterni, operazioni amministrative e interazioni umane. Il flag critical e la classe default_approval contribuiscono alla matrice del modulo. Non dimostrano, da soli, che una richiesta di conferma sia presentata nel percorso di esecuzione corrente.

Per esempio, compute:pure e time:read hanno classe none; fs:write ha classe per_target; mail:send, mail:write, system:admin e drive:permissions hanno classe always. L'elenco completo va letto dal registro, non mantenuto a mano in questa pagina.

3. Tabella autonomia × capability

La matrice è il prodotto dei tre livelli di autonomia (ReadOnly, Supervised, Full) per le capacità registrate. Per ogni cella produce un esito: allowed, approval_required o denied. È generata da _init_table. Qui sotto compare un estratto; il comando table stampa la matrice completa.

3.1 Le tre regole che generano la tabella

La tabella non è arbitraria: nasce da tre regole, una per livello, che _init_table applica iterando sul registro.

ReadOnly. Le capacità non critiche con classe none sono consentite. Un insieme esplicito di letture e accessi circoscritti — fra cui fs:read, mail:read, calendar:read, network:sites e provider:access — produce approval_required. Le altre capacità critiche o con approvazione predefinita vengono negate.

Supervised. Le capacità con classe none sono consentite; tutte le altre producono approval_required. Questa è la semantica della matrice, non la prova che il dispatcher corrente presenti il relativo dialogo.

Full. Le capacità con classe always producono ancora approval_required; tutte le altre sono consentite. Fra le voci correnti con classe always figurano code:exec, mail:send, mail:write, system:admin e drive:permissions.

Un esito non equivale a un controllo applicato. La matrice conserva approval_required per le classi always anche al livello Full. Finché il dispatcher non usa questo esito come vincolo generale, la proprietà va letta come contratto del modulo e non come garanzia dell'intero sistema.

La reversibilità in pratica: il motore di undo

La reversibilità è un contratto distinto dalla matrice di autonomia. Un executor conforme allo standard che dichiara revertible = true deve indicare un reverse_pattern. Il runtime conserva i dati di esecuzione necessari e undo_last_turn prova ad applicare il percorso inverso, riferendo anche gli eventuali fallimenti.

Il catalogo chiuso in runtime/reverse_patterns.py comprende, fra gli altri:

• swap_src_dst — uno spostamento o rinomina si annulla scambiando sorgente e destinazione (path del filesystem e cartelle IMAP allo stesso modo, le seconde agganciate allo stabile Message-ID).
• delete_created_dirs / delete_created_paths — una creazione si annulla rimuovendo ciò che è stato creato, solo finché è ancora vuoto/intatto.
• restore_blob_backup — prima di ogni scrittura distruttiva il runtime salva una copia byte della versione precedente in $METNOS_HISTORY_DIR/<turn>/blob/<sha256>.bin; l'undo la ripristina. È la parte «intercetta la modifica e tieni una copia della versione precedente», fatta una volta e in modo deterministico.
• i pattern delete_*_by_id — una creazione su un servizio esterno si annulla usando l'identificatore restituito dall'operazione.

Per i manifest conformi allo standard, il validatore controlla la coerenza fra la dichiarazione di reversibilità e il pattern inverso. Restano percorsi di compatibilità per alcuni executor manuali: per questo non è corretto affermare che ogni operazione modificatrice usi soltanto il catalogo.

La presenza di un pattern inverso non concede autorità e non elimina, da sola, un'eventuale approvazione. Reversibilità, autorizzazione e isolamento sono controlli separati.

4. Concessioni persistenti per bersaglio

Il modulo offre anche un archivio SQLite per concessioni circoscritte. Ogni record lega un canale, un mittente, una capacità, un obiettivo e un'eventuale scadenza. L'archivio esiste ed è interrogabile; il percorso ordinario di approvazione non vi scrive ancora concessioni.

4.1 Schema SQLite

Lo schema è definito da runtime/policy.py:SCHEMA:

CREATE TABLE IF NOT EXISTS grants (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 channel TEXT NOT NULL,
 sender_id TEXT NOT NULL,
 capability TEXT NOT NULL,
 target TEXT NOT NULL,
 granted_at TEXT NOT NULL,
 expires_at TEXT,
 granted_by TEXT,
 revoked_at TEXT
);

Una concessione è identificata dalla quaterna (channel, sender_id, capability, target). Le date granted_at, expires_at e revoked_at sono espresse in UTC. La separazione logica fra utenti dipende dal corretto passaggio di canale e mittente da parte del chiamante.

Il file predefinito è ~/.local/state/metnos/grants.db per l'utente di installazione; METNOS_GRANTS_DB permette di indicarne un altro. Più utenti applicativi serviti dallo stesso processo condividono dunque il contenitore fisico, mentre le righe restano distinte dall'identità fornita all'API.

4.2 API

Le funzioni aprono e chiudono una connessione per chiamata; non mantengono una sessione SQLite globale.

4.3 Stato dell'integrazione

Nel runtime corrente non risultano chiamanti di produzione di record_grant e il pianificatore non consulta effective_outcome. La tabella può essere popolata chiamando direttamente l'API del modulo, ma non esiste una superficie amministrativa attiva che lo faccia e non va descritta come la memoria delle conferme dell'utente.

5. Esito combinato (effective_outcome)

La funzione effective_outcome combina la matrice e le concessioni in un unico esito. È disponibile ai chiamanti del modulo e alla CLI; non è attualmente il punto di accesso del pianificatore.

La logica è lineare: se la tabella decide già in modo netto (allowed o denied), il grant non viene neppure consultato; se decide approval_required, un grant attivo lo trasforma in allowed, altrimenti resta approval_required.

Invariante della funzione: una concessione non trasforma mai denied in allowed. Può invece trasformare approval_required in allowed.

Limite da conoscere. effective_outcome non distingue fra per_target e always quando trova una concessione attiva. Anche una capacità classificata always verrebbe quindi elevata ad allowed se qualcuno ne registrasse una concessione. Prima di collegare il modulo al dispatcher occorre impedire questo caso oppure definire esplicitamente una semantica diversa.

5.1 Esempio verificabile

Valutazione del modulo, non esecuzione di un turno. Il comando check Supervised fs:write, senza identità e obiettivo, restituisce approval_required. Il comando check ReadOnly fs:write restituisce denied. Questi risultati mostrano la matrice; non salvano un file e non aprono un dialogo nella chat.

6. Integrazione runtime

Il modulo partecipa al runtime nei punti seguenti:

• il validatore dei manifest usa CAPABILITY_REGISTRY per rifiutare nomi sconosciuti;
• effective_outcome è richiamato dalla CLI, ma non dal percorso ordinario del pianificatore o del dispatcher;
• approval_registry e il relativo renderer di canale non hanno chiamanti di produzione che creino richieste pendenti;
• i dialoghi attivi di conferma seguono il contratto semantico descritto in esperienza di approvazione: azione, scopo, conseguenze e scelte ammesse, senza imporre un numero fisso di righe o pulsanti.

Di conseguenza questo archivio di concessioni non va interpretato come il meccanismo di autorizzazione attivo del pianificatore. Un eventuale chiamante deve conservare identità e obiettivo esatti, rispettare l'isolamento per utente, gestire correttamente le classi always e usare un renderer semantico localizzato.

7. CLI

Dal percorso principale del repository, il modulo è ispezionabile con l'ambiente di Metnos. Espone cinque sottocomandi.

I comandi registry, table e grants producono JSON Lines e possono essere filtrati con jq.

8. Come verificare il modulo

La verifica del modulo comprende:

• importare il modulo con l'ambiente di Metnos;
• eseguire registry, table e i casi check desiderati;
• eseguire i test del validatore dei manifest, che controllano anche il rifiuto delle capacità sconosciute;
• verificare separatamente il dialogo get_approval, che è il meccanismo attivo e non dipende da questo archivio di concessioni.

9. Confini della policy

• Registro chiuso. Solo le capacità canoniche possono entrare nella tabella o ricevere un permesso. Un executor con una capacità sconosciuta non viene ammesso per analogia.
• Identità fornita dal chiamante. Le concessioni sono distinte per canale e mittente, ma il modulo non autentica da solo questi valori. L'isolamento effettivo deve essere imposto dal livello che lo chiamerà.
• Nessuna elevazione di un diniego. Una concessione non supera denied; il trattamento delle classi always resta invece da correggere prima dell'integrazione.
• Responsabilità separate. Frequenza, costo, disponibilità del fornitore e isolamento del processo appartengono ad altri livelli. La policy non li deduce e non li maschera.

Note finali

Il valore attuale del modulo è circoscritto ma concreto: registro chiuso, matrice deterministica e archivio strutturato. La garanzia pubblica resta limitata a ciò che il runtime collega davvero.

Presentare questa API come filtro generale prima del collegamento al dispatcher sarebbe un'affermazione più ampia del comportamento dimostrato.