La lib agent — Modello Nativo ad Attori (agent, send, receive), KV Store e Rate Limiter

38.1. Perché esiste la lib agent? (Il problema reale e la filosofia Ridgun)

«Perché ho bisogno di una lib agent scritta da zero in Ridgun puro invece di collegare una libreria C tradizionale?»

Questa è la prima domanda che si pone qualsiasi ingegnere di sistema arrivando a agent. E la risposta riassume l'intera filosofia di ridgun-libs:

Siamo sinceri: condividere memoria mutabile tra thread con Mutex, RwLock e variabili di condizione è una fabbrica inesauribile di deadlock e race condition.

La lib agent sfrutta il Modello Nativo di Agenti di Ridgun (agent, send ... to, receive from, try receive from, stop) per offrire mailbox isolate con passaggio di messaggi Copy-on-Write, uno store chiave-valore concorrente (KvStore), un rate limiter a token bucket (RateBucket) e supervisione dello stato (AgentHealth).

In un ecosistema tradizionale, risolvere i compiti del dominio AGENT comporta trascinare dipendenze esterne in C, gestire puntatori grezzi, conversioni opache di tipo, eccezioni non verificate o pause imprevedibili del garbage collector. In Ridgun, la lib agent (src/main/ridgun/lib/agent.rg) affronta il problema con quattro principi non negoziabili:

1. Dichiara import agent (o import agent as alias) all'inizio del file: ogni lib definisce il proprio spazio dei nomi module :: agent e in modalità --strict le funzioni multi-parola si invocano sempre con spazi naturali.
2. Concatena le tue pipeline da sinistra a destra con ->: scrivi input passo uno -> passo due -> risultato, usa le maschere (+ _ _ +) per destrutturare le sequenze e ometti _ = nelle istruzioni sequenziali (o scarta il valore con -> ()).
3. Ricorsione di coda con TCO (Tail-Call Optimization): tutte le scansioni interne di agent vengono compilate in cicli nativi in spazio di stack $O(1)$.
4. Memoria deterministica (RMM1 / RMM2): ogni struttura intermedia viene liberata nell'istante esatto in cui termina la sua ultima lettura, senza Garbage Collector.

---

38.2. Artefatti nativi, importazione e catalogo completo dell'API di agent

In ridgun-libs, agent è una lib di prima classe situata in src/main/ridgun/lib/agent.rg (dominio AGENT). Compilando con stable bundle, viene impacchettata in tre artefatti nativi:

Artefatto	Percorso	Scopo
Bundle Ridgun	target/bundles/agent.rglib	Distribuzione e importazione diretta con import agent
File compilato	target/agent.rgc	Artefatto intermedio verificato da ridgunc
Oggetto condiviso ELF64	target/libagent.so	Libreria dinamica nativa senza dipendenze C né libc

Ogni lib dichiara il proprio spazio dei nomi con module :: agent: basta scrivere import agent (o import agent as alias) nell'intestazione e invocare le sue funzioni con spazi naturali (mia funzione x) e pipeline -> (x mia funzione -> risultato).

38.2.1. Riepilogo delle famiglie funzionali di agent

Firma / Funzione / Tipo	Cosa fa e quando usarla
agent roundtrip / agent drain count	Avvia attori nativi (agent), scambia messaggi (send ... to / receive from) ed esegue stop
kv store new / kv store apply	Store chiave-valore immutabile per attori (KvPut, KvGet, KvDelete, KvClear)
rate bucket new / rate bucket allow	Rate limiter a token bucket che restituisce il bucket aggiornato e (allowed, remaining)
sup mark failed / sup should restart	Politiche di supervisione con controllo del budget di riavvio (max_restarts)

38.2.2. Catalogo esaustivo dei tipi e delle firme in src/main/ridgun/lib/agent.rg

Di seguito trovi l'inventario completo dei tipi algebrici (type), degli operatori (op ::) e delle firme di funzione (fn ::) definiti in src/main/ridgun/lib/agent.rg (7 tipi, 0 operatori e 65 funzioni):

Tipi algebrici e record (type) di agent:

type AgentStatus = AgentRunning | AgentStopped | AgentTimedOut Int | AgentFailed String
type AgentReply  = ReplyInt Int | ReplyStr String | ReplyBool Bool | ReplyEmpty | ReplyStopped | ReplyTimeout Int | ReplyError String
type CounterState = cnt_val: Int
type KvCmd        = KvPut String String | KvGet String | KvDel String | KvHas String | KvCount | KvKeys | KvClear
type KvEntry      = kv_k: String, kv_v: String
type KvState      = kv_size: Int, kv_items: [KvEntry]
type LogState     = log_sep: String, log_buf: String

#	Funzione / Firma (fn ::)	Tipo di Ritorno
1	fn :: format agent status AgentStatus	String
2	fn :: format agent reply AgentReply	String
3	fn :: is agent alive (Agent A B)	Bool
4	fn :: agent status (Agent A B)	AgentStatus
5	fn :: stop agent (Agent A B)	AgentStatus
6	fn :: agent stop all [Agent]	()
7	fn :: agent ask Agent A	B
8	fn :: agent try ask Agent A	Option
9	fn :: agent send batch Agent [A]	()
10	fn :: agent receive count Agent Int	[B]
11	fn :: agent receive count loop Agent Int [B]	[B]
12	fn :: agent map batch Agent [A]	[B]
13	fn :: agent list len [A] Int	Int
14	fn :: agent drain ready Agent	[B]
15	fn :: agent drain ready loop Agent [B]	[B]
16	fn :: agent drain step Agent Option [B]	[B]
17	fn :: ag cast opt A	B
18	fn :: ag unwrap try int (Option Int)	AgentReply
19	fn :: ag unwrap try str (Option String)	AgentReply
20	fn :: ask int (Agent Int Int) Int	AgentReply
21	fn :: ask str (Agent String String) String	AgentReply
22	fn :: try poll int (Agent A Int)	AgentReply
23	fn :: try poll str (Agent A String)	AgentReply
24	fn :: ag poll int step (Agent Int Int) (Option Int) Int Int	AgentReply
25	fn :: ag wait int loop (Agent Int Int) Int Int	AgentReply
26	fn :: ask int with timeout (Agent Int Int) Int Int	AgentReply
27	fn :: ag poll str step (Agent String String) (Option String) Int Int	AgentReply
28	fn :: ag wait str loop (Agent String String) Int Int	AgentReply
29	fn :: ask str with timeout (Agent String String) String Int	AgentReply
30	fn :: ask batch int (Agent Int Int) [Int]	[Int]
31	fn :: ask batch str (Agent String String) [String]	[String]
32	fn :: relay int (Agent Int Int) (Agent Int Int) Int	AgentReply
33	fn :: relay str (Agent String String) (Agent String String) String	AgentReply
34	fn :: ag counter step CounterState Int	CounterState Int
35	fn :: new counter agent Int	Agent Int Int
36	fn :: counter add (Agent Int Int) Int	Int
37	fn :: counter get (Agent Int Int)	Int
38	fn :: counter reset (Agent Int Int)	Int
39	fn :: ag log join String String String	String
40	fn :: ag log step LogState String	LogState String
41	fn :: new log agent String	Agent String String
42	fn :: log append (Agent String String) String	String
43	fn :: log read (Agent String String)	String
44	fn :: log clear (Agent String String)	String
45	fn :: ag kv lookup [KvEntry] String	String
46	fn :: ag kv exists [KvEntry] String	Bool
47	fn :: ag kv put list [KvEntry] String String	[KvEntry]
48	fn :: ag kv del list [KvEntry] String	[KvEntry]
49	fn :: ag kv len [KvEntry]	Int
50	fn :: ag kv keys join String String	String
51	fn :: ag kv keys str [KvEntry]	String
52	fn :: ag kv has str Bool	String
53	fn :: ag kv next state KvState KvCmd	KvState
54	fn :: ag kv next reply KvState KvCmd	String
55	fn :: ag kv step KvState KvCmd	KvState String
56	fn :: new kv agent	Agent KvCmd String
57	fn :: ag kv call (Agent KvCmd String) KvCmd	String
58	fn :: kv put (Agent KvCmd String) String String	String
59	fn :: kv get (Agent KvCmd String) String	String
60	fn :: kv delete (Agent KvCmd String) String	String
61	fn :: kv has (Agent KvCmd String) String	Bool
62	fn :: ag parse int String	Int
63	fn :: kv count (Agent KvCmd String)	Int
64	fn :: kv keys (Agent KvCmd String)	String
65	fn :: kv clear (Agent KvCmd String)	String

---

38.3. Esplorare agent a fondo: Esempi passo dopo passo di ogni funzionalità

Non basta consultare la tabella delle firme: esploreremo ciascuna delle funzionalità della lib agent tramite esempi progressivi ed eseguibili in Ridgun. Inizieremo con due ricette tabulari di uso quotidiano e poi percorreremo nel dettaglio tutti gli scenari funzionali, le trasformazioni e i casi limite verificati in src/test/ridgun/test agent.rg.

38.3.1. Esempio 1: Flusso principale in stile tabulare con agent

Osserva come in Ridgun i segni = e i passaggi di trasformazione con agent risultino allineati come una tabella pulita, senza variabili mutabili superflue né effetti collaterali nascosti:

import agent

fn :: probar contador actor => Int Int
      probar contador actor =
        10 new counter agent -> ag
        counter add ag 32 -> v1
        ag counter get -> v2
        ag stop agent -> ()
        (v1, v2)

38.3.2. Esempio 2: Composizione sicura e gestione dei casi limite

Ogni funzione della lib agent è progettata per comporsi con le guardie booleane | e con il resto delle 34 lib di ridgun-libs:

import agent

fn :: consultar almacen kv => String Int
      consultar almacen kv =
        new kv agent -> kv
        kv put kv "modo" "produccion" -> ()
        kv get kv "modo" -> modo
        kv count kv -> total
        kv stop agent -> ()
        (modo, total)

38.3.3. Esempio 3: Combinatori di attori (agent ask, try ask, send batch, map batch, drain ready), pool partizionati e reattore di connessioni

In questo esempio pratico esploriamo in modo esaustivo come si comporta agent in questo blocco funzionale, inclusi input standard, combinazioni di parametri e valori di frontiera:

fn :: test spec combinators pool and net agent => ()
      test spec combinators pool and net agent =
        w1 = agent (ag double worker)
        assert int equals (agent ask w1 21) 42 "agent ask 21 -> 42"
        mb = agent map batch w1 [3, 5, 7]
        assert int equals (ag sum ints mb) 30 "agent map batch [3,5,7] -> [6,10,14] sum 30"
        agent send batch w1 [10, 20] -> ()
        rc = agent receive count w1 2
        assert int equals (ag sum ints rc) 60 "agent send batch + agent receive count -> 60"
        c_dr = new counter agent 100
        send 5 to c_dr
        send 10 to c_dr
        dr = agent drain ready c_dr
        assert int equals (ag sum ints dr) 220 "agent drain ready [105, 115] -> 220"
        agent stop all [w1, c_dr] -> ()
        assert false (is agent alive w1) "w1 stopped by agent stop all"
        assert false (is agent alive c_dr) "c_dr stopped by agent stop all"

        s0 = new counter agent 0
        s1 = new counter agent 1000
        pl = Pool 2 [s0, s1]
        assert int equals (pool size pl) 2 "pool size 2"
        assert int equals (pool ask shard pl 0 5) 5 "pool ask shard 0 -> 5"
        assert int equals (pool ask shard pl 1 7) 1007 "pool ask shard 1 -> 1007"
        assert int equals (pool ask shard pl (0 - 3) 3) 1010 "pool ask shard negative key -> shard 1"
        pool broadcast pl 10 -> ()
        all_dr = pool drain all pl
        assert int equals (ag sum ints all_dr) 1035 "pool drain all [15, 1020] -> 1035"
        pool shutdown pl -> ()
        assert false (is agent alive s0) "pool s0 stopped"
        assert false (is agent alive s1) "pool s1 stopped"

        ca = agent (ag echo conn step) (CounterState 0)
        cb = agent (ag echo conn step) (CounterState 0)
        s_eof = conn feed payload (0 - 1) ca ""
        s_err = conn handle event (0 - 1) cb 8
        kept  = reactor sweep next s_eof (reactor sweep next s_err [])
        assert int equals (agent list len kept 0) 0 "reactor sweep next prunes closed slots"
        assert false (is agent alive ca) "ca stopped on EOF"
        assert false (is agent alive cb) "cb stopped on POLLERR"
        cc = agent (ag echo conn step) (CounterState 0)
        reactor shutdown [ConnSlot (0 - 1) cc] -> ()
        assert false (is agent alive cc) "cc stopped on reactor shutdown"

38.3.4. Esempio 4: Ciclo di vita degli agenti (is agent alive, agent status, stop agent) e agente contatore con stato isolato (new counter agent)

In questo esempio pratico esploriamo in modo esaustivo come si comporta agent in questo blocco funzionale, inclusi input standard, combinazioni di parametri e valori di frontiera:

fn :: test agent lifecycle and counter => ()
      test agent lifecycle and counter =
        assert str eq (format agent status AgentRunning) "running" "format AgentRunning"
        assert str eq (format agent status AgentStopped) "stopped" "format AgentStopped"
        assert str eq (format agent status (AgentTimedOut 250)) "timeout after 250 ms" "format AgentTimedOut"
        assert str eq (format agent status (AgentFailed "boom")) "failed: boom" "format AgentFailed"
        assert str eq (format agent reply (ReplyInt 42)) "42" "format ReplyInt"
        assert str eq (format agent reply (ReplyStr "ok")) "ok" "format ReplyStr"
        assert str eq (format agent reply (ReplyBool True)) "true" "format ReplyBool True"
        assert str eq (format agent reply (ReplyBool False)) "false" "format ReplyBool False"
        assert str eq (format agent reply ReplyEmpty) "agent outbox empty" "format ReplyEmpty"
        assert str eq (format agent reply ReplyStopped) "agent stopped" "format ReplyStopped"
        assert str eq (format agent reply (ReplyTimeout 50)) "agent timeout after 50 ms" "format ReplyTimeout"
        assert str eq (format agent reply (ReplyError "bad")) "agent error: bad" "format ReplyError"

        c   = new counter agent 10
        assert ok (is agent alive c)
        assert str eq (format agent status (agent status c)) "running" "counter running"
        assert str eq (format agent reply (try poll int c)) "agent outbox empty" "empty outbox before send"
        assert eq (counter get c) 10
        assert eq (counter add c 5) 15
        assert eq (counter add c 7) 22
        assert str eq (format agent reply (ask int c 8)) "30" "ask int 8 -> 30"
        assert str eq (format agent reply (ask int with timeout c 12 200)) "42" "ask int with timeout -> 42"
        assert eq (counter reset c) 0
        assert eq (counter get c) 0
        bs  = ask batch int c [1, 2, 3, 4]
        assert eq (ag sum ints bs) 20

        c2  = new counter agent 100
        rel = relay int c c2 5
        assert str eq (format agent reply rel) "115" "relay int c (10+5=15) -> c2 (100+15=115)"

        st1 = stop agent c
        assert str eq (format agent status st1) "stopped" "stop agent returns AgentStopped"
        assert eq (is agent alive c) False
        assert str eq (format agent status (agent status c)) "stopped" "agent status after stop"
        assert str eq (format agent reply (ask int c 1)) "agent stopped" "ask int after stop"
        assert str eq (format agent reply (try poll int c)) "agent stopped" "try poll int after stop"
        assert str eq (format agent reply (ask int with timeout c 1 50)) "agent stopped" "ask int with timeout after stop"
        assert str eq (format agent reply (relay int c c2 1)) "agent stopped" "relay int after stop"
        c0  = new counter agent 0
        assert int equals (counter get c0) 0 "counter 0 initial"
        assert int equals (counter add c0 3) 3 "counter 0 add 3"
        stop agent c0
        stop agent c2
        assert eq (is agent alive c2) False

38.3.5. Esempio 5: Agente di registro append-only (new log agent) e store chiave-valore in memoria tramite scambio di messaggi (new kv agent)

In questo esempio pratico esploriamo in modo esaustivo come si comporta agent in questo blocco funzionale, inclusi input standard, combinazioni di parametri e valori di frontiera:

fn :: test log and kv agents => ()
      test log and kv agents =
        lg  = new log agent "\n"
        assert ok (is agent alive lg)
        assert str eq (format agent reply (try poll str lg)) "agent outbox empty" "log empty outbox"
        assert str eq (log read lg) "" "initial log empty"
        assert str eq (log append lg "alpha") "alpha" "log append alpha"
        assert str eq (log append lg "beta") "alpha\nbeta" "log append beta"
        assert str eq (format agent reply (ask str with timeout lg "gamma" 200)) "alpha\nbeta\ngamma" "ask str with timeout gamma"
        assert str eq (log read lg) "alpha\nbeta\ngamma" "log read"
        assert str eq (log clear lg) "" "log clear"
        assert str eq (log read lg) "" "log read after clear"
        b   = ask batch str lg ["one", "two"]
        assert str eq (ag join strs b) "one|one\ntwo" "ask batch str"
        lg2 = new log agent ":"
        assert str eq (format agent reply (relay str lg lg2 "three")) "one\ntwo\nthree" "relay str"
        stop agent lg
        stop agent lg2
        assert str eq (format agent reply (ask str lg "x")) "agent stopped" "ask str after stop"

        kv  = new kv agent
        assert ok (is agent alive kv)
        assert int equals (kv count kv) 0 "kv count 0"
        assert false (kv has kv "host") "kv has host false"
        assert str eq (kv put kv "host" "127.0.0.1") "127.0.0.1" "kv put host"
        assert str eq (kv put kv "port" "8080") "8080" "kv put port"
        assert int equals (kv count kv) 2 "kv count 2"
        assert ok (kv has kv "host")
        assert ok (kv has kv "port")
        assert str eq (kv get kv "host") "127.0.0.1" "kv get host"
        assert str eq (kv get kv "port") "8080" "kv get port"
        assert str eq (kv keys kv) "host,port" "kv keys"
        assert str eq (kv put kv "port" "9090") "9090" "kv overwrite port"
        assert str eq (kv get kv "port") "9090" "kv get updated port"
        assert int equals (kv count kv) 2 "kv count after overwrite"
        assert str eq (kv delete kv "host") "127.0.0.1" "kv delete host"
        assert false (kv has kv "host") "kv has host after delete"
        assert int equals (kv count kv) 1 "kv count 1"
        assert str eq (kv clear kv) "" "kv clear"
        assert int equals (kv count kv) 0 "kv count after clear"
        stop agent kv
        assert false (is agent alive kv) "kv stopped"

---

38.4. Sotto il cofano: come è costruita agent in Ridgun puro (src/main/ridgun/lib/agent.rg)

Uno dei maggiori vantaggi di ridgun-libs è che non ci sono scatole nere in C. Puoi aprire src/main/ridgun/lib/agent.rg e leggere esattamente come è implementata ogni operazione usando pattern matching, alberi di guardie | / |. e ricorsione di coda (TCO). Vediamo i pezzi chiave della sua implementazione reale:

38.4.1. Implementazione interna: Status & Reply Formatting

Nota come agent.rg strutturi prima le firme fn :: ... => ... e risolva ogni caso tramite equazioni allineate e chiamate di coda:

module :: agent

fn :: format agent status AgentStatus        => String
      format agent status AgentRunning       =  "running"
      format agent status AgentStopped       =  "stopped"
      format agent status (AgentTimedOut ms) =  "timeout after {ms} ms"
      format agent status (AgentFailed   msg) = "failed: {msg}"

fn :: format agent reply AgentReply        => String
      format agent reply (ReplyInt     n)  =  int to str n
      format agent reply (ReplyStr     s)  =  s
      format agent reply (ReplyBool True)  =  "true"
      format agent reply (ReplyBool False) =  "false"
      format agent reply ReplyEmpty        =  "agent outbox empty"
      format agent reply ReplyStopped      =  "agent stopped"
      format agent reply (ReplyTimeout ms) =  "agent timeout after {ms} ms"
      format agent reply (ReplyError  msg) =  "agent error: {msg}"

38.4.2. Implementazione interna: Core Combinators (agent ask, agent try ask, agent send batch, agent receive count, agent map batch, agent drain ready)

Nota come agent.rg strutturi prima le firme fn :: ... => ... e risolva ogni caso tramite equazioni allineate e chiamate di coda:

fn :: agent ask Agent A   => B
      agent ask ag    msg =  ask ag msg

fn :: agent try ask Agent A   => Option
      agent try ask ag    msg =
        send msg to ag
        try receive from ag

fn :: agent send batch Agent [A]      => ()
      agent send batch _     []       =  ()
      agent send batch ag    (m:rest) =
        send m to ag
        agent send batch ag rest

fn :: agent receive count Agent Int   => [B]
      agent receive count ag    count =  agent receive count loop ag count []

fn :: agent receive count loop Agent Int [B] => [B]
      agent receive count loop ag count acc
        | count <= 0 = acc
        | otherwise =
          r = receive from ag
          agent receive count loop ag (count - 1) (acc :: [r])

fn :: agent map batch Agent [A]  => [B]
      agent map batch ag    msgs =
        agent list len msgs 0 -> n
        agent send batch ag msgs -> ()
        agent receive count ag n

fn :: agent list len [A]    Int => Int
      agent list len []     acc =  acc
      agent list len (_:xs) acc =  agent list len xs (acc + 1)

fn :: agent drain ready Agent => [B]
      agent drain ready ag    =  agent drain ready loop ag []

fn :: agent drain ready loop Agent [B] => [B]
      agent drain ready loop ag acc =
        agent drain step ag (try receive from ag) acc

fn :: agent drain step Agent Option [B] => [B]
      agent drain step _ None acc = acc
      agent drain step ag (Some r) acc = agent drain ready loop ag (acc :: [r])

38.4.3. Implementazione interna: Stateful Counter Agent (new counter agent, counter add, counter get, counter reset)

Nota come agent.rg strutturi prima le firme fn :: ... => ... e risolva ogni caso tramite equazioni allineate e chiamate di coda:

fn :: ag counter step CounterState Int   => CounterState Int
      ag counter step st           delta =
        | delta == (0 - 999999999) = (CounterState 0, 0)
        | otherwise                =
          nxt = (cnt_val st) + delta
          (CounterState nxt, nxt)

fn :: new counter agent Int  => Agent Int Int
      new counter agent init =  agent (ag counter step) (CounterState init)

fn :: counter add (Agent Int Int) Int   => Int
      counter add ag              delta =
        | not (agent alive ag) = 0
        | otherwise            =
          _ = send delta to ag
          receive from ag

fn :: counter get (Agent Int Int) => Int
      counter get ag              =  counter add ag 0

fn :: counter reset (Agent Int Int) => Int
      counter reset ag              =  counter add ag (0 - 999999999)

38.4.4. Implementazione interna: Stateful In-Memory Key-Value Agent (new kv agent, kv put, kv get, kv delete, kv has, kv count, kv keys, kv clear)

Nota come agent.rg strutturi prima le firme fn :: ... => ... e risolva ogni caso tramite equazioni allineate e chiamate di coda:

fn :: ag kv lookup [KvEntry] String => String
      ag kv lookup []        _      =  ""
      ag kv lookup (e:rest)  key    =
        | (kv_k e) == key = kv_v e
        | otherwise       = ag kv lookup rest key

fn :: ag kv exists [KvEntry] String => Bool
      ag kv exists []        _      =  False
      ag kv exists (e:rest)  key    =
        | (kv_k e) == key = True
        | otherwise       = ag kv exists rest key

fn :: ag kv put list [KvEntry] String String => [KvEntry]
      ag kv put list [] key val = [KvEntry key val]
      ag kv put list (e:rest) key val =
        | (kv_k e) == key = [KvEntry key val] :: rest
        | otherwise       = [e] :: (ag kv put list rest key val)

fn :: ag kv del list [KvEntry] String => [KvEntry]
      ag kv del list [] _ = []
      ag kv del list (e:rest) key =
        | (kv_k e) == key = rest
        | otherwise       = [e] :: (ag kv del list rest key)

fn :: ag kv len [KvEntry] => Int
      ag kv len []        =  0
      ag kv len (_:rest)  =  1 + (ag kv len rest)

fn :: ag kv keys join String String => String
      ag kv keys join k rest_s =
        | (str len rest_s) == 0 = k
        | otherwise             = k + "," + rest_s

fn :: ag kv keys str [KvEntry] => String
      ag kv keys str []        =  ""
      ag kv keys str (e:rest)  =  ag kv keys join (kv_k e) (ag kv keys str rest)

fn :: ag kv has str Bool  => String
      ag kv has str True  =  "1"
      ag kv has str False =  "0"

---

38.5. Garanzie algoritmiche, memoria RMM1/RMM2 e le 5 Regole d'Oro di agent

• Garanzia algoritmica e di sicurezza: Zero memoria mutabile condivisa tra attori: ogni messaggio viene trasferito per valore / Copy-on-Write e stop libera la regione dell'agente in modo deterministico.
• Complessità dello stack $O(1)$ con TCO: Tutti i cicli ricorsivi in src/main/ridgun/lib/agent.rg sono in posizione di coda, perciò ridgunc li compila in salti nativi senza crescita dello stack.
• Memoria deterministica (RMM1/RMM2): Zero pause del garbage collector; tutte le strutture intermedie vengono liberate in modo deterministico all'uscita dallo scope.
• Verifica continua: Testata in modo esaustivo con stable check e la suite automatizzata src/test/ridgun/test agent.rg.

Le 5 Regole d'Oro quando programmi con agent

1. Dichiara import agent all'inizio del file e usa le funzioni multi-parola con spazi naturali affinché il tuo codice si legga come prosa.
2. Allinea le tue pipeline di dati con = e ->: concatena le chiamate a agent in passaggi con nomi chiari e lascia che stable format allinei le colonne.
3. Sfrutta le funzioni totali di agent nelle tue guardie |: controlla i valori di ritorno o destruttura gli ADT con pattern matching invece di dare per scontato che l'input esterno sia sempre valido.
4. Evita di copiare grandi strutture se devi solo consultare un campo: ricorda che in RMM2 gli argomenti di input sono prestati e non incrementano né decrementano i contatori (+0 / -0).
5. Combina agent con test (import test): scrivi sempre asserzioni con assert equals o assert true per fissare gli invarianti del tuo dominio.

---

Nel Capitolo 39 passeremo a esplorare in profondità la lib pool (La lib pool — Pool Limitato di Worker, Round-Robin e Work-Stealing).