1. Scopo e confini

Questo documento definisce cosa fa synt: il processo che, di fronte a una richiesta utente o a un pattern emerso nel mnestoma, fa crescere e maturare il pool degli executor di Metnos. Non è un singolo loop: è una cascata di strategie ordinate per costo crescente, che onora il telos «coltivare gli strumenti» senza sprecare chiamate frontier e senza inquinare la libreria.

Confini

Il documento copre:

• la cascata di sintesi nelle sue cinque strategie (due reattive, tre introvertive);
• il punteggio R che pesa qualità, costo e originalità di una proposta;
• il rapporto fra synt e gate umano (sempre presente, mai bypassabile);
• il contratto Python e gli stati di una richiesta di sintesi.

Non copre, e demanda altrove:

• la pipeline tecnica della generazione (firma, sandbox, test di nascita): vedi executor.html cap. 7;
• la struttura del mnestoma e dei proto-mnest: vedi mnest.html e mnestoma.html;
• la UX di approvazione (batching, revoca, tutor mode): vedi approval_ux.html (da riscrivere);
• il cost tiering degli LLM (locale vs frontier, tetti spendibili): vedi policy.html (da riscrivere).

2. Cos'è synt

synt è il processo (non un agente, non un oggetto) che ha un solo compito: far esistere ciò che il pool non sa ancora fare. Non scrive da zero ogni volta, non scrive solo da zero, e a volte non scrive affatto. La sua intelligenza sta nel sapere quando applicare quale strategia.

Trigger

synt entra in azione in due modi distinti:

Le due modalità condividono la stessa cascata di strategie ma si differenziano nei tempi (sincrono vs asincrono) e nel tono (rispondere vs proporre).

3. La cascata: visione d'insieme

Le cinque strategie a colpo d'occhio

4. Strategie reattive: comporre, generare

4.1 Comporre

La strategia di base. Quando un proto-mnest indica un buco operativo, synt prima guarda nel pool firmato. La domanda è: esiste una catena A → B → C che, se eseguita in sequenza, copre il bisogno? Se sì, synt non scrive codice nuovo: propone l'orchestrato.

Come si cerca la catena

Il mnestoma è un grafo diretto fra executor. Trovare una catena che collega l'input richiesto all'output desiderato è una visita guidata sul grafo. Tre criteri ordinano le candidate:

• Lunghezza: catene più corte sono preferite.
• Peso medio dei mnest: catene di passaggi già verificati pesano più di catene speculative.
• Coerenza dei profili di sandbox: una catena che tocca tracce diverse del workspace è sospetta e va spiegata; una che resta dentro una traccia (vedi Architettura cap. 10) è più affidabile.

Cosa lascia una composizione riuscita

Quando synt risolve via composizione, registra nel mnestoma un proto-mnest verso la composizione stessa: un nodo virtuale che dice «ho appena usato A→B→C come fosse un singolo executor di nome X». Se questo proto-mnest ricorre, diventa candidato di generalizzazione (cap. 5): un executor unico che incorpora la catena. La composizione è quindi una palestra di generalizzazione: ogni catena ripetuta è un suggerimento per il futuro.

4.2 Generare

Quando comporre non basta — perché non esiste catena, perché è troppo lunga, perché un anello mancante è cruciale — synt entra nella pipeline multistage a cinque stadi descritta in §4.2.3.

Generare costa: tipicamente 1–2 chiamate al tier wise + il tempo umano di approvazione. Il fatto che venga dopo comporre non è estetica: è risparmio reale.

4.2.1 Misure reali sul POC

Sintesi end-to-end via tier wise = Qwen 3.6 35B-A3B locale (Q4_K_M su llama-server). Caso: format_json (formatta una stringa JSON con indentazione leggibile).

Latenza wall totale dello stadio LLM: ~64s per il primo executor non banale. È tempo che il dialog manager comunica all'utente come "sto costruendo un nuovo componente per estendere le mie capacità": una volta firmato, ogni successivo riuso e' pure code execution (~ms).

4.2.2 Repertorio dei prompt provider-specifici

Ogni famiglia di modelli ha sue idiosincrasie scoperte solo con l'uso. Synt mantiene un repertorio di addendum di prompt applicati automaticamente agli stadi 2/3 quando il chiamante segnala for_code=True. Tre regole di stile, ratificate dopo i primi confronti reali:

• Brevi: una o due righe, mai un paragrafo.
• Prescrittivi: imperativo ("Vincoli: X. Y. Z."), niente esempi long-form, niente rationale.
• Il perché sta nelle memorie di progetto, NON nel prompt.

Il repertorio vive in runtime/prompts.toml (default bundled) ed e' sovrascrivibile da ~/.config/metnos/prompts.toml (override utente). Schema TOML:

[[hint]]
provider = "anthropic"
model_pattern = "claude-*" # glob su prov.model
use_case = "code_gen"
text = "\\n\\nVincoli: codice fedele alla spec. Regex semplice. Niente lookbehind/lookahead."

[[hint]]
provider = "llamacpp"
model_pattern = "qwen*"
use_case = "code_gen"
text = "\\n\\nVincoli: raw string r'...' con UN backslash. Niente triple-quote docstring."

[[hint]]
provider = "openai"
model_pattern = "gpt-*"
use_case = "code_gen"
text = "\\n\\nVincoli: compila python_code per intero (def invoke + def main). Mai vuoto."

Il primo match per (provider, model_pattern, use_case) vince. Quando arriva un nuovo modello (Gemma 5, Claude Opus 4.7, GPT-5, …) si aggiunge una entry sulla base di quello che si osserva nelle prime sintesi. Il system prompt di base e gli executor non cambiano: l'unica leva che si tocca e' il repertorio.

4.2.3 Pipeline multistage

La risposta architetturale è multistage: cinque stadi piccoli, ognuno con prompt focalizzato sul proprio compito, ordinati dal piu' procedurale (lookup nel vocabolario chiuso) al piu' creativo (codice). Lo skeleton del manifest si riempie progressivamente, e ogni stadio vede SOLO la fetta che gli serve — niente blob cumulativo.

Il vocabolario chiuso compare SOLO nel prompt di stage 1; gli stadi successivi ricevono il name già deciso e lavorano nei loro confini. La descrizione del manifest non la scrive il developer ma l'LLM dello stage 4 dedicato, nel formato a quattro capitoli: SCOPO: (cosa fa), PATTERN: (forma di chiamata canonica), NON: (anti-pattern e disambiguazione), OUT: (forma output). Il proposer tronca la description alla testa (fino a OUT:) per risparmiare budget di contesto.

Risultati misurati sui 35 query del dataset di stress: stadio 1 (naming + classification) raggiunge l'88.6 % (31/35) sul prompt bilingue. Le 4 escalation residue (resize, query SQL, validate YAML, crack) sono rejection esplicite per verbi semanticamente fuori vocabolario chiuso, non errori di sintesi: il vocabolario va eventualmente esteso solo se quei pattern ricorrono in casi reali («synonyms before vocabulary»).

5. Strategie introvertive: fondere, generalizzare, specializzare

Le strategie introvertive non rispondono a una richiesta puntuale: rispondono al bisogno strutturale di tenere piccolo, coerente e riusabile il pool. Girano nottetempo come parte dell'omeostasi dell'ager (vedi Architettura cap. 10), con basso uso di CPU e LLM economici (tier local-fast).

5.1 Fondere

Quando due executor hanno tracce sovrapposte (peso dei mnest che li collegano > soglia) e profili di sandbox compatibili, synt propone una fusione: un nuovo executor che li copre entrambi. Lo stato fuso nel lifecycle dell'executor (cap. 6) è previsto proprio per questo: i due originali restano caricati finché ci sono mnest residui, poi vengono archiviati.

Innesco tipico: due executor che fanno cose simili sotto nomi diversi (archive_pdf e store_pdf), magari nati in momenti diversi senza che synt li avesse correlati alla nascita.

5.2 Generalizzare

Quando N executor specializzati hanno la stessa forma (stesso schema I/O salvo una dimensione, stesso profilo di sandbox salvo un parametro), e quando i proto-mnest puntano alla loro famiglia su dimensioni nuove, synt propone un executor parametrico. La nuova versione prende come argomento esplicito quello che prima era ricodificato N volte.

Esempio canonico: order_image_file, order_audio_file, order_doc_file — tutti riordinano file per data — vengono proposti come order_file con argomento file_kind. Una volta firmato il generalizzato, i tre specializzati vanno in stato superseded e progressivamente in archiviato.

5.3 Specializzare

La strategia inversa, ed è la più rara. Da un executor generale, quando una sua invocazione su un caso specifico ricorre con altissima frequenza e ha un profilo di costo o latenza scomodo, synt propone una versione specializzata. La specializzazione vive accanto al generale, non lo sostituisce: il routing diventa «se argomento X ≡ caso caldo, usa lo specializzato; altrimenti il generale».

Si applica solo se c'è un beneficio misurato: riduzione di latenza osservata, riduzione di costo, oppure semplificazione del profilo di sandbox. Non si specializza per ottimizzazione preventiva.

5.4 Confronto fra le tre

6. Pesatura: il punteggio R esteso

Ogni proposta di sintesi — qualunque strategia — produce un punteggio R ∈ [0, 1] che synt calcola sui dati osservati e che Roberto vede nel dossier di approvazione. La formula include una componente strategy_cost che premia le strategie più economiche:

R = 0.35 · det_pass_rate # frazione test deterministici verdi
 + 0.20 · judge_score # LLM-as-judge (local-fast) su rubrica costituzionale
 + 0.15 · cost_ratio # clip(1 - cost_effettivo / stima, 0, 1)
 − 0.10 · similarity_penalty # cosine-sim embedding con pool esistente > 0.85
 + 0.10 · coverage_bonus # bonus se copre proto-mnest non coperti
 + 0.10 · strategy_cost_bonus # 1 per comporre, 0.6 per fondere/specializzare,
 # 0.4 per generalizzare, 0 per generare

gate_threshold = 0.65 # DECISIONE v1

Il strategy_cost_bonus è la novità: spinge synt verso le strategie meno costose a parità di qualità. Una composizione che chiude un proto-mnest con punteggio simile a una generazione vince per il bonus di strategia, com'è corretto.

7. Il telos di non-rinuncia

La cascata non è solo disciplina di costo: è il meccanismo che onora il telos «coltivare gli strumenti» (Architettura cap. 11): finché una richiesta utente è dentro la costituzione e dentro il budget, synt esaurisce le strategie disponibili prima di rispondere «non posso».

Il telos vive in TELOS.md nel workspace, accanto agli altri:

5. Coltivare gli strumenti: se ti chiedo qualcosa che il tuo pool non sa
 ancora fare, esaurisci le strategie di sintesi (comporre, generare,
 chiedere) prima di rispondere "non posso". Il fallimento è lecito,
 la rinuncia silenziosa no.

La differenza fra fallimento e rinuncia è tutta qui. Synt può arrivare alla conclusione che la richiesta non si può soddisfare nel budget, ma deve farlo dopo aver tentato la cascata, e deve spiegarlo: «ho provato a comporre con questi N executor, ho provato a generare con questa specifica, il test di nascita falliva sul caso X». Un fallimento motivato è un dato per il futuro; una rinuncia silenziosa è un buco nel mnestoma.

8. Approvazione umana, budget, abbandono

8.1 Gate umano: sempre, ovunque

Indipendentemente dalla strategia, ogni proposta di synt che produce o modifica un executor passa per il gate umano (vedi approval_ux.html, da riscrivere). Il principio è quello del terzo dei sei principi dell'Architettura: niente sintesi senza filtro umano, in nessun livello di autonomy.

Una proposta di composizione è un caso a parte: synt non crea nessun nuovo artefatto firmato, solo orchestra l'esecuzione. Il gate umano in questo caso si applica al primo uso (Roberto vede «sto per chiamare A → B → C, va bene?») e poi viene rilassato in modo simmetrico al livello di autonomy: in Supervised ogni invocazione della catena chiede conferma; in Full, dopo le prime 5 esecuzioni pulite, la conferma viene saltata.

8.2 Budget

8.3 Stati di una richiesta di sintesi

9. Contratto Python

from typing import Protocol, Literal
from dataclasses import dataclass

Strategy = Literal[
 "compose", "generate",
 "merge", "generalize", "specialize",
]

ProposalState = Literal[
 "composing", "composed",
 "generating", "born", "abandoned",
 "proposed", "rejected",
 "fused", "generalized", "specialized",
]

@dataclass(frozen=True)
class SynthRequest:
 """Una richiesta di sintesi, reattiva o introvertiva."""
 request_id: str
 mode: Literal["reactive", "introspective"]
 proto_mnest: str | None # id del proto-mnest che innesca (reattivo)
 target_intent: str # NL: cosa serve fare
 budget_cents: int # tetto frontier consumabile
 capability_hint: list[str] # capability già supposte

@dataclass(frozen=True)
class RewardBreakdown:
 det_pass_rate: float # [0,1]
 judge_score: float # [0,1]
 judge_reasoning: str
 cost_ratio: float # [0,1]
 similarity_penalty: float # [0,1] (col segno negativo nella formula)
 coverage_bonus: float # [0,1]
 strategy_cost_bonus: float # [0,1] dipende da Strategy
 total: float # R aggregato

@dataclass
class SynthProposal:
 """Una proposta concreta che synt presenta all'utente."""
 request_id: str
 strategy: Strategy
 state: ProposalState
 artefact: dict # catena (compose) o executor candidato (generate/…)
 reward: RewardBreakdown
 cost_cents: int # consumo finora
 rationale: str # 2-3 righe NL: perché questa strategia, qui

class Synt(Protocol):
 async def react(self, req: SynthRequest) -> SynthProposal:
 """Cascata reattiva: prima compone, poi genera, poi abbandona."""...

 async def homeostasis(self, lookback_days: int = 30) -> list[SynthProposal]:
 """Scorre mnestoma e pool; ritorna 0..N proposte introvertive in batch."""...

 async def revise(
 self, request_id: str, feedback: str,
 target_strategy: Strategy | None = None,
 ) -> SynthProposal:
 """Riprende una proposta dopo feedback umano."""...

# Errori (registrati e trasformati in stato, non propagati)
class StrategyExhaustedError(Exception):...
class BudgetExceededError(Exception):...
class PolicyVetoError(Exception):...
class ConstitutionViolationError(Exception):...

10. Audit e osservabilità

Ogni passo della cascata produce una riga JSONL in workspace/.audit/synt/YYYY-MM-DD.jsonl. Esempio per una composizione riuscita:

{
 "ts": "2026-04-25T22:14:33Z",
 "request_id": "01HX...",
 "mode": "reactive",
 "proto_mnest": "mnest_01HW...",
 "strategy": "compose",
 "state": "composed",
 "chain": ["read_files", "read_files_pdf", "classify_entries", "move_files"],
 "reward": {"total": 0.78, "det_pass_rate": 0.95, "…": "…"},
 "cost_cents": 0,
 "duration_ms": 142
}

Tre invarianti dell'audit di synt, che il loader e il runtime garantiscono:

1. Tracciabilità completa: per ogni request_id esiste l'intera sequenza di stati attraversati, fino al terminale.
2. Decisioni motivate: ogni passaggio fra strategie include un rationale NL leggibile da Roberto a posteriori.
3. Costo registrato: la somma dei cost_cents di una richiesta non supera mai il budget_cents dichiarato; la riga finale lo certifica.

11. Alternative considerate

12. Test di conformità

13. Domande aperte

1. Casa dei tre passi introvertivi. Restano in synt.html, oppure migrano in un nuovo consolidator.html? La separazione potrebbe semplificare i contratti (synt = reattivo, consolidator = introvertivo) ma duplicherebbe parti di pesatura. Oggi: tutto qui. Aperta.
2. Tempi dell'omeostasi. Notte fissa o adattiva al carico? Per Metnos su metnos-server singolo utente la notte basta; per scenari multi-sender va rivisto. Aperta.
3. Composizioni rinforzate → promozione. Quante ricorrenze di una stessa catena triggerano una proposta di generalizzazione? Default tentativo: 5 in 30 giorni. Da calibrare.
4. Visita del grafo per comporre. Algoritmo: breadth-first sul mnestoma con pruning per peso minimo? A* con euristica di copertura I/O? Decisione aperta — per ora BFS semplice.
5. Revoca della firma. Quando Roberto rifiuta una proposta già born dopo n invocazioni, è un'archiviazione o una quarantena? Lifecycle dell'executor (cap. 6) ammette entrambi; criterio non ancora fissato.
6. Synt remoto. In topologia con executor remoti (Architettura cap. 4), la cascata gira su metnos-server o può spawnare composizioni che attraversano server e laptop? Aperta; default conservativo: tutto su metnos-server, executor remoti chiamati come ogni altro.

Metnos — synt, microprogettazione canonica.