@mmmbuto/nexuscrew 0.9.29 → 0.9.31

package/lib/fleet/cell-lease-server.js

@@ -4,10 +4,10 @@
 //
 // Fetta 2b (contratto rev1): l'autenticazione del reconnect e' un proof HMAC
 // firmato con un verifier PER-INSTALLAZIONE — la capability statica condivisa
-// della 2a e' REVOCATA, non affiancata (A2/B1). Solo il server conosce il
-// segreto; il supervisore presenta un proof firmato con claims ed expiry (B8:
+// Della 2a e' REVOCATA, non affiancata (/). Solo il server conosce il
+// Segreto; il supervisore presenta un proof firmato con claims ed expiry (
 // issuedAt+60s). Il proof supervisore arriva al detentore sul canale lease
-// (all'attach e a ogni refresh) e non transita mai nel child (R3.1.2 invariato).
+// (on attach and on every refresh) and never transits to the child.
 //
 // Storage per-cella (da revisione): un file per cella in <run>/cell-leases/. Il
 // refresh di una cella rilegge e riscrive SOLO il proprio file: scompare la
@@ -15,22 +15,22 @@
 // l'amplificazione O(N^2) misurata in 2a (N letture + N scritture complete
 // per ciclo di 20s). L'invariante di recovery post-restart e' preservato ed
 // affinato: un file corrotto salta solo la propria cella, non lo store intero
-// (E3 chiusa con test). Il nome file usa la stessa sanitizeCell dell'endpoint
+// (closed with tests). Il nome file usa la stessa sanitizeCell dell'endpoint
 // UDS: due cellId che sanitizzano uguale condividono file ed endpoint, proprieta'
 // gia' vera in 2a per il socket.
 //
-// Rotazione (C3, sospesa per scelta dichiarata): finche' la finestra di
+// Key rotation (suspended by declared choice): finche' la finestra di
 // sovrapposizione non e' fissata la chiave NON ruota; la verifica interroga
 // comunque la LISTA delle chiavi vive (oggi una) perche' quella e' la forma
-// richiesta da C2 quando la rotazione sara' attivata. Fail-closed sulla
-// verifica (C4); lo stato durevole non contiene mai il segreto, solo
-// identificativo e impronta nel meta del verifier (C5); la verifica rende
-// osservabile quale chiave ha firmato (C6, via log del keyId).
+// Richiesta da quando la rotazione sara' attivata. Fail-closed sulla
+// Verifica; lo stato durevole non contiene mai il segreto, solo
+// Identificativo e impronta nel meta del verifier; la verifica rende
+// Osservabile quale chiave ha firmato (via log del keyId).
 //
 // Side effect isolati e iniettabili (seams) per testabilita', come altrove nel
 // fleet (cell-exec.js, launch-broker.js). Protocollo sul socket lease:
 // line-oriented JSON, un messaggio per riga.
-//   supervisor -> server: {"type":"generation","generation":..}   (R1)
+// Supervisor -> server: {"type":"generation","generation":..}
 //   supervisor -> server: {"type":"refresh"}
 //   supervisor -> server: {"type":"reconnect","generation":..,"proof":{..}}
 //   server     -> supervisor: {"type":"lease","leaseId":..,"proof":{..}}
@@ -58,7 +58,7 @@ function validCellId(cellId) { return typeof cellId === 'string' && CELL_ID_RE.t
 // ingresso): la validazione e' UNA, non due copie da tenere allineate.
 const EPOCH_RE = /^[a-f0-9]{16}$/;
 
-// A3 — confine del consumo: un proof e' consumato UNA volta, IN-PROCESS. Il
+// Confine del consumo: un proof e' consumato UNA volta, IN-PROCESS. Il
 // registro dei jti muore col processo server: dopo un restart un proof non
 // ancora scaduto puo' ripresentarsi (la firma e l'expiry restano il gate).
 // Garanzia piu' forte (single-use cross-restart) NON promessa dal contratto.
@@ -79,12 +79,12 @@ function createLeaseManager(cfg = {}, seams = {}) {
   // cellId -> entry:
   //   { launchEpoch, stablePath, stableServer, lease, socket, graceTimer, graceDeadline, lastCommit }
   // lease/socket/lastCommit vivono in memoria (persi al restart); launchEpoch/
-  // graceDeadline sono anche persistiti PER CELLA (D1). lastCommit è il frutto
-  // dell'ultimo commitBound riuscito (IC1): t/deadline/issuedAt da cui derivare
+  // GraceDeadline sono anche persistiti PER CELLA. lastCommit è il frutto
+  // Dell'ultimo commitBound riuscito: t/deadline/issuedAt da cui derivare
   // i proof senza rileggere il clock. Nessun segreto in entry o su disco.
   const cells = new Map();
 
-  // Verifier per-installazione (B7): file dedicato 0o600 nella runtime dir,
+  // Verifier per-installazione: file dedicato 0o600 nella runtime dir,
   // distinto dai token di liveness e dal segreto del bridge audio. Lazy: nasce
   // al primo proof, cosi' un manager che non firma mai non lascia file in giro.
   let verifier = null;
@@ -92,10 +92,10 @@ function createLeaseManager(cfg = {}, seams = {}) {
     if (!verifier) verifier = loadOrCreateVerifier({ dir, fsImpl: fs, log });
     return verifier;
   }
-  // Le chiavi vive per la verifica (C2-ready, oggi una: C3 sospesa).
+  // Le chiavi vive per la verifica (-ready, oggi una: sospesa).
   const liveKeys = () => [ensureVerifier()];
 
-  // Registro jti consumati (A3): bounded, i scaduti escono da soli.
+  // Registro jti consumati: bounded, i scaduti escono da soli.
   const consumedJti = new Map(); // jti -> expiresAt
   function consumeJti(jti, expiresAt) {
     const t = now();
@@ -110,10 +110,10 @@ function createLeaseManager(cfg = {}, seams = {}) {
     return true;
   }
 
-  // Proof supervisore (kind 'lease'): tupla con leaseId (B6), generation
-  // corrente, expiry issuedAt+60s (B8). Emissione == firma: non c'e' stato di
+  // Proof supervisore (kind 'lease'): tupla con leaseId, generation
+  // Corrente, expiry issuedAt+60s. Emissione == firma: non c'e' stato di
   // sessione da tenere, il detentore presenta il proof cosi' com'e'.
-  // IC1.1 (rev28, emendata da rev29): quando il proof nasce da un commit del
+  // Per the amended contract: quando il proof nasce da un commit del
   // bound, issuedAt è DERIVATO da D (D − PROOF_TTL_MS), mai letto dal clock:
   // expiresAt = issuedAt + TTL è esattamente D, senza toccare verifyProof,
   // KIND_FIELDS o wire (vincolo della revisione).
@@ -133,7 +133,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
 
   function stablePathFor(cellId) { return path.join(dir, `cell-${sanitizeCell(cellId)}.sock`); }
 
-  // D1: lettura PER CELLA. ENOENT = cella sconosciuta (legittimo); qualunque
+  // Lettura PER CELLA. ENOENT = cella sconosciuta (legittimo); qualunque
   // altro errore (EIO, parse, forma) = illeggibile: propaga, perche' una
   // scrittura che ignora un file illeggibile cancellerebbe lo stato di quella
   // cella senza saperlo.
@@ -155,7 +155,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
   }
 
   function writePersistedCell(cellId, entryData) {
-    // IC8.2/IC8.3 (rev29): l'esito NON si ingoia — ritornato perche' il refresh (e il
+    // The outcome is never swallowed: l'esito NON si ingoia — ritornato perche' il refresh (e il
     // proof) dipende dal commit effettivo del bound. Il log resta diagnostico.
     try {
       ensureRuntimeDir(dir);
@@ -172,13 +172,13 @@ function createLeaseManager(cfg = {}, seams = {}) {
     }
   }
 
-  // D1: persiste il bound di UNA cella leggendo e scrivendo SOLO il suo file.
+  // Persiste il bound di UNA cella leggendo e scrivendo SOLO il suo file.
   // Non esiste piu' la read-modify-write dell'intero store condiviso.
-  // IC8.1 (rev29): graceDeadline SEMPRE valorizzato come intero valido (mai
+  // The persisted graceDeadline SEMPRE valorizzato come intero valido (mai
   // null) — bound durevole per rifiutare reconnect oltre la grace post-restart
-  // (R3.3.5). Live = now+PROOF_TTL_MS (IC1: l'ancora live e' la vita del
-  // proof, non la grace); in grace = bound di armGrace (R3.2); refresh lo
-  // rinfresca.
+  // Live = now + PROOF_TTL_MS (the live anchor is the proof lifetime,
+  // not the grace); in grace = the armGrace bound; refresh renews it.
+
   function persistEntry(cellId, entry) {
     return writePersistedCell(cellId, {
       launchEpoch: entry.launchEpoch,
@@ -186,26 +186,26 @@ function createLeaseManager(cfg = {}, seams = {}) {
     });
   }
 
-  // IC1 (rev28, come emendata da rev29) — UNA deadline D per (cella,
+  // One deadline D per (cell, incarnation): UNA deadline D per (cella,
   // incarnazione). Il bound persistito e l'expiry del proof NON sono due valori
   // coordinati: sono LO STESSO VALORE. La transazione legge il clock UNA volta
   // sola; D = max(D corrente, t + PROOF_TTL_MS) — monotona non decrescente
-  // (IC1.2); il proof nasce con issuedAt = D − PROOF_TTL_MS, quindi expiresAt
+  //; il proof nasce con issuedAt = D − PROOF_TTL_MS, quindi expiresAt
   // === D per costruzione e verifyProof (expiresAt === issuedAt + TTL) resta
   // intatto. La persistenza è SINCRONA (writeFileSync + renameSync) e l'intera
   // transazione update→persist→ACK+proof vive in un solo giro di event loop:
-  // indivisibile (IC1.3). La serializzazione viene dal runtime (IC4.1/IC9.1) —
+  // Indivisibile. La serializzazione viene dal runtime (/) —
   // dichiarato qui, non assunto altrove.
   // L'ancora del bound LIVE è la vita del proof (PROOF_TTL_MS), non la grace:
-  // GRACE_MS resta l'ancora della grace a EOF (R3.2). I due valori oggi
-  // coincidono (60s): cambia l'ancora semantica, non il numero.
+  // GRACE_MS remains the anchor of the EOF grace. The two values currently
+  // coincide (60s): the semantic anchor changes, not the number.
   function commitBound(cellId, entry) {
     const t = now(); // unica lettura del clock per l'intera transazione
     const proposed = t + PROOF_TTL_MS;
     const current = Number.isSafeInteger(entry.graceDeadline) && entry.graceDeadline > 0 ? entry.graceDeadline : 0;
-    const D = Math.max(current, proposed); // IC1.2: mai all'indietro
+    const D = Math.max(current, proposed); // Mai all'indietro
     if (D <= t) {
-      // IC1.6: D già scaduta al commit NON è un successo: niente ACK, niente
+      // D già scaduta al commit NON è un successo: niente ACK, niente
       // proof. Con proposed = t + TTL è irraggiungibile per costruzione; la
       // guardia resta perché vieta l'implementazione alternativa (D derivata
       // da dati stantii) che il contratto esclude.
@@ -227,7 +227,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
 
   function armGraceTimer(cellId, entry) {
     clearGraceTimer(entry);
-    // R3.2: deadline non estendibile, armata una sola volta.
+    // Non-extendable deadline, armed once.
     const ms = Math.max(0, (entry.lease.graceDeadline - now()));
     entry.graceTimer = setTimer(() => {
       const e = cells.get(cellId);
@@ -250,7 +250,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
     // record non committa, rollback e ritorna false: il caller non dichiarera' lease.
     // Diverso da EOF (onEOF): li una write fallita lascia un bound ANTERIORE (fail-closed
     // anticipato, accettabile); qui il bind prometterebbe stato live senza commit durevole.
-    // IC1: il commit passa da commitBound — UNA deadline, monotona, ancorata alla
+    // Il commit passa da commitBound — UNA deadline, monotona, ancorata alla
     // vita del proof. entry.lastCommit (SOLO in memoria: il formato per-cella su
     // disco non cambia) porta t/issuedAt al caller, perché il proof del frame
     // lease nasca derivato da D senza nuove letture di clock.
@@ -278,12 +278,12 @@ function createLeaseManager(cfg = {}, seams = {}) {
         return;
       }
       if (msg.type === 'refresh') {
-        // Heartbeat lato supervisore (R3.2) + IC1 (rev28/rev29): il refresh
-        // committa LA deadline D — monotona, ed è l'expiry del proof che sta
-        // per nascere — e SOLO se il commit è durevole emette ACK+proof IN UN
-        // SOLO FRAME (IC1.4). Se la persistenza non committa il refresh NON è
-        // un successo — nessun ACK, nessun proof (IC8.2/8.4): il detentore
-        // resta col proof vecchio, che scade: fail-closed per scadenza, non per
+        // Supervisor-side heartbeat: the refresh commits THE deadline D — monotonic,
+        // and it is the expiry of the proof about to be born — and ONLY if the
+        // Commit is durable does it emit ACK+proof IN ONE SINGLE FRAME.
+        // If persistence does not commit, the refresh is NOT a success — no ACK,
+        // No proof (/8.4): the holder keeps the old proof, which expires:
+        // fail-closed by expiry, not by silence.
         // silenzio.
         const cur = cells.get(cellId);
         if (cur && cur.lease && cur.socket === socket) {
@@ -314,13 +314,13 @@ function createLeaseManager(cfg = {}, seams = {}) {
     const onEOF = () => {
       const cur = cells.get(cellId);
       if (!cur || cur.socket !== socket) return; // gia' sostituita da un reconnect
-      // R3.1.3: EOF arma UNA sola transizione monotonica Live -> Grace; deadline
-      // non estendibile. armGrace e' no-op se gia' in grace.
+      // EOF arms a SINGLE monotonic Live -> Grace transition; deadline
+      // not extendable. armGrace is a no-op if already in grace.
       const g = L.armGrace(cur.lease, { now: now() });
       if (g) cur.lease = g;
-      // R3.3.5: persistiamo il nuovo bound di grace per rifiutare reconnect stale
-      // post-restart (il lease vivo non sopravvive, ma il bound di reject si').
-      // IC1.2: il bound non arretra nemmeno qui — eof >= ultimo refresh rende la
+      // We persist the new grace bound to reject stale reconnects
+      // post-restart (the live lease does not survive, but the reject bound does).
+      // Il bound non arretra nemmeno qui — eof >= ultimo refresh rende la
       // grace già monotona in pratica; il max la pinna anche sotto clock ostile.
       const graceBound = cur.lease && cur.lease.graceDeadline != null ? cur.lease.graceDeadline : now() + L.GRACE_MS;
       cur.graceDeadline = Math.max(
@@ -400,7 +400,7 @@ function createLeaseManager(cfg = {}, seams = {}) {
       && validDaemonChallenge(msg.challenge);
   }
 
-  // R1: transizione di generazione della connessione viva. Solo stessa
+  // Transizione di generazione della connessione viva. Solo stessa
   // generazione (idempotente) o +1 (restart del supervisore); generazioni
   // arbitrarie restano deny -> il relay fail-closed (revoked) non cambia.
   function validGenerationRequest(msg) {
@@ -484,7 +484,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
   // viaggia, ma la decisione resta qui: l'authority ri-calcola l'HMAC, la
   // finestra temporale, il replay (nonce single-use) e la revoca (jti), e i
   // claims vengono confrontati col SUBJECT AUTENTICATO del lancio — mai con
-  // campi del messaggio (C7-bis). Fail-closed: qualunque esito non ok resta
+  // Campi del messaggio (-bis). Fail-closed: qualunque esito non ok resta
   // una negazione motivata, il canale non apre nulla.
   function handleVerify(cellId, entry, socket, msg) {
     if (!validVerifyRequest(msg)) {
@@ -548,7 +548,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
   }
 
   function onStableConnection(cellId, socket) {
-    // Endpoint stabile: reconnect (R3.3.2-4). Legge identita' + proof, valida.
+    // Stable endpoint: reconnect. Reads identity + proof, validates.
     let buf = '';
     const onData = (chunk) => {
       buf += chunk.toString();
@@ -580,10 +580,10 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     if (!msg || msg.type !== 'reconnect') return denyReconnect(socket);
     const entry = cells.get(cellId);
     if (!entry) return denyReconnect(socket);
-    // A2/B1: l'autenticazione del reconnect e' il proof HMAC. La capability
+    // : l'autenticazione del reconnect e' il proof HMAC. La capability
     // statica della 2a e' revocata: un messaggio senza proof (o col vecchio
     // campo capability) e' negato qui, senza confronti verso segreti condivisi.
-    // C4: fail-closed — forma, firma, claims attesi, expiry: ogni difetto e' deny.
+    // Fail-closed — forma, firma, claims attesi, expiry: ogni difetto e' deny.
     const out = verifyProof(liveKeys(), msg.proof, {
       now,
       expect: {
@@ -591,7 +591,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
         cellId,
         launchEpoch: entry.launchEpoch,
         // leaseId atteso SOLO con lease vivo in memoria: post-restart il lease
-        // non sopravvive (R3.3.1) e il gate resta firma+expiry+bound di grace.
+        // does not survive, and the gate stays signature+expiry+grace-bound.
         ...(entry.lease ? { leaseId: entry.lease.leaseId } : {}),
       },
     });
@@ -599,7 +599,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       log(`cell-lease: ${cellId} reconnect denied (proof: ${out.reason})`);
       return denyReconnect(socket);
     }
-    // A3: consumo il jti DOPO la verifica e PRIMA di ogni mutazione. Un proof
+    // Consumo il jti DOPO la verifica e PRIMA di ogni mutazione. Un proof
     // presentato e negato per altro motivo NON viene consumato: potra' ripresentarsi
     // fino alla propria scadenza, e ogni replica sara' negata dallo stesso gate.
     if (!consumeJti(msg.proof.jti, msg.proof.expiresAt)) {
@@ -607,25 +607,25 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       return denyReconnect(socket);
     }
     const generation = Number.isInteger(msg.generation) && msg.generation >= 0 ? msg.generation : (entry.lease ? entry.lease.generation : 0);
-    // R3.3.4: transizione di generation VERIFICABILE (non solo non-decreasing). Il
-    // supervisore onesto (cell-exec.js) fa avanzare la generation di ESATTAMENTE +1
-    // a ogni restart del child e al reconnect presenta sempre la propria generation
-    // corrente. La transizione attesa e' quindi `=== current` (stesso restart,
-    // retry/reattach) oppure `=== current + 1` (un restart del supervisore). Un salto
-    // avanti arbitrario (es. 0->99) o all'indietro NON e' una transizione che il
-    // client onesto produrrebbe: deny. msg.generation assente -> fallback alla
-    // current (compat), accettato. Post-restart (entry.lease null) non c'e' generation
-    // persistita da validare (contratto rev25 EC6): firma+bound di grace resta il gate.
+    // A VERIFIABLE generation transition (not merely non-decreasing). An honest
+    // supervisor (cell-exec.js) advances the generation by EXACTLY +1 on every
+    // child restart and always presents its current generation on reconnect.
+    // The expected transition is therefore `=== current` (same restart,
+    // retry/reattach) or `=== current + 1` (one supervisor restart). An arbitrary
+    // jump forward (e.g. 0->99) or backward is NOT a transition an honest
+    // client would produce: deny. Missing msg.generation -> fallback to current
+    // (compat), accepted. Post-restart (entry.lease null) there is no persisted
+    // generation to validate: signature + grace bound stay the gate.
     if (entry.lease && Number.isInteger(msg.generation)) {
       const cur = entry.lease.generation;
       if (msg.generation !== cur && msg.generation !== cur + 1) {
         return denyReconnect(socket);
       }
     }
-    // R3.3.5/IC8.1 (rev29): oltre la grace il reconnect e' rifiutato. Con entry.lease
-    // vivo ci pensa reattach (null su grace scaduta). Post-restart (lease null) usiamo
-    // il bound di grace persistito PER CELLA, ora SEMPRE valorizzato: se la richiesta
-    // arriva ALLA deadline o oltre, rifiuta (>= allineato a cell-lease.js).
+    // Past the grace the reconnect is refused. With a live entry.lease
+    // reattach handles it (null on an expired grace). Post-restart (lease null) we
+    // use the per-cell persisted grace bound, now ALWAYS set: if the request
+    // arrives AT or past the deadline, refuse (>= aligned with cell-lease.js).
     // Recovery post-restart con supervisore/child vivi solo ENTRO il bound live.
     if (!entry.lease && now() >= entry.graceDeadline) {
       return denyReconnect(socket);
@@ -635,12 +635,12 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       ? L.reattach(entry.lease, { leaseId: L.newLeaseId(), generation, now: now() })
       : base;
     if (!reattached) return denyReconnect(socket);
-    // R3.3.4: lease NUOVO (leaseId nuovo), stessa identita'. Associa la nuova connessione.
+    // NEW lease (new leaseId), same identity. Binds the new connection.
     if (!bindLiveSocket(cellId, entry, socket, { lease: reattached })) {
       return denyReconnect(socket);
     }
-    log(`cell-lease: ${cellId} reconnect ok (lease ${reattached.leaseId}, verifier ${out.keyId})`); // C6: chiave osservabile
-    // IC1.1: il proof del frame lease nasce DAL commit appena fatto (issuedAt =
+    log(`cell-lease: ${cellId} reconnect ok (lease ${reattached.leaseId}, verifier ${out.keyId})`); // Chiave osservabile
+    // Il proof del frame lease nasce DAL commit appena fatto (issuedAt =
     // D − TTL): stessa deadline del bound appena persistito, non una lettura di
     // clock nuova. bindLiveSocket riuscito implica commit fatto: il ramo senza
     // proof è difensivo (fail-closed: il detentore resta col proof pregresso,
@@ -653,10 +653,10 @@ function handleChallengeProof(cellId, entry, socket, msg) {
 
   // --- API pubblica ---
 
-  // Apre l'endpoint stabile UDS 0o600 per una cella (R3.3.2), riusando l'identity
-  // e lo stablePath gia' noti nell'entry. Idempotente: se l'entry ha gia' uno
-  // stableServer vivo non fa nulla. Condiviso da track() (prima apertura) e da
-  // boot() (riapertura dopo restart per le celle persistite).
+  // Opens the per-cell stable UDS endpoint 0o600, reusing the entry's known
+  // identity and stablePath. Idempotent: if the entry already has a live
+  // stableServer it does nothing. Shared by track() (first open) and
+  // boot() (reopen after restart for persisted cells).
   async function openEndpoint(cellId, entry) {
     if (entry.stableServer) return entry.stablePath;
     ensureRuntimeDir(dir);
@@ -675,7 +675,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       server.listen(sp, () => {
         server.removeListener('error', reject);
         server.unref();
-        // Il chmod forza/verifica 0o600; il suo fallimento NON va ingoiato (R3.3.2).
+        // The chmod enforces/verifies 0o600; its failure must NOT be swallowed.
         try {
           fsImpl.chmodSync(sp, 0o600);
         } catch (e) {
@@ -748,7 +748,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       || crypto.randomBytes(8).toString('hex');
     const entry = existing
       || { launchEpoch, stablePath: stablePathFor(cellId), stableServer: null, lease: null, socket: null, graceTimer: null,
-        // IC1: anche il bound iniziale di una cella nuova è ancorato alla vita
+        // Anche il bound iniziale di una cella nuova è ancorato alla vita
         // del proof (PROOF_TTL_MS), stesso valore di GRACE_MS ma stessa semantica
         // del commit live che seguirà.
         graceDeadline: now() + PROOF_TTL_MS, lastCommit: null };
@@ -784,12 +784,12 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     return { stablePath: entry.stablePath, launchEpoch };
   }
 
-  // Recovery di produzione (R3.3.1 fail-closed): al boot del server la map e'
-  // vuota e nessun lease sopravvive. Ricarichiamo {launchEpoch, graceDeadline}
-  // persistiti PER CELLA e RIAPRIAMO l'endpoint stabile per ogni cella nota,
-  // cosicche' un supervisore vivo che reconnecta dopo il restart trovi
-  // l'endpoint. La verifica del proof non richiede stato ricostruito: la chiave
-  // verifier e' persistita per-installazione.
+  // Production recovery (fail-closed): at server boot the map is empty
+  // and no lease survives. We reload the per-cell persisted
+  // {launchEpoch, graceDeadline} and REOPEN the stable endpoint for every
+  // known cell, so that a live supervisor reconnecting after the restart
+  // finds the endpoint. The proof check needs no rebuilt state: the verifier
+  // key is persisted per-installation.
   async function boot() {
     loadPersisted();
     for (const [cellId, entry] of cells) {
@@ -802,17 +802,17 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     }
   }
 
-  // Connessione broker one-shot iniziale (R3.1.1): autenticata dal nonce del
-  // broker; qui associiamo la connessione al lease (primo contatto).
-  // 2b: attachInitial NON scrive nulla sul canale. Durante la consegna del
-  // payload il canale appartiene al protocollo del broker (frame length-
-  // prefixed u32): una riga JSON scritta prima del payload corromperebbe la
-  // lettura di receivePayload e il child non nascerebbe — misurato dal gate
-  // (da revisione interna, esito positivo). Il proof supervisore arriva con
-  // l'ACK del primo refresh, che il lease-client invia IMMEDIATAMENTE
-  // all'avvio: la finestra attach->primo-ack senza proof detenuto e' fail-closed
-  // (reconnect negato -> grace -> onLost), coerente col modello per cui nessun
-  // commit persistito = nessuna recovery promessa.
+  // Initial one-shot broker connection: authenticated by the broker nonce;
+  // here we bind the connection to the lease (first contact).
+  // attachInitial writes nothing on the wire. While the payload is delivered
+  // the channel belongs to the broker protocol (length-prefixed u32 frames):
+  // a JSON line written before the payload would corrupt the receivePayload
+  // read and the child would never be born — measured by the gate
+  // (internal review, positive result). The supervisor proof arrives with the
+  // ACK of the first refresh, which the lease-client sends IMMEDIATELY at
+  // startup: the attach->first-ack window without a held proof is fail-closed
+  // (reconnect refused -> grace -> onLost), consistent with the model that no
+  // persisted commit means no promised recovery.
   function attachInitial(cellId, socket, { generation = 0 } = {}) {
     const entry = cells.get(cellId);
     if (!entry) return false;
@@ -821,11 +821,11 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     return bindLiveSocket(cellId, entry, socket, { lease });
   }
 
-  // Al boot del server (R3.3.1 fail-closed): la map e' vuota. Ricarichiamo solo
-  // {launchEpoch, graceDeadline} persistiti PER CELLA (D1), per riconoscere le
-  // identity (il proof le porta firmate) e per rifiutare reconnect oltre la
-  // grace (R3.3.5). Nessun lease/eligibilita' sopravvive.
-  // E3: un file malformato/corrotto salta la PROPRIA cella (logged); le altre
+  // At server boot (fail-closed): the map is empty. We reload only the
+  // {launchEpoch, graceDeadline} persisted PER CELL, to recognize the
+  // identities (the proof carries them signed) and to reject reconnects past
+  // the grace. No lease/eligibility survives.
+  // Un file malformato/corrotto salta la PROPRIA cella (logged); le altre
   // caricano. Con lo store unico di 2a un parse error buttava tutte.
   function loadPersisted() {
     let files;
@@ -857,7 +857,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
       // validarli anche quando la cella non sia ancora passata di nuovo per track().
       cells.set(cellId, {
         launchEpoch: info.launchEpoch,
-        // IC8.5 (rev29): graceDeadline assente/illeggibile/non-intero = bound trattato come scaduto (0 -> deny sempre).
+        // A missing/unreadable/non-integer graceDeadline assente/illeggibile/non-intero = bound trattato come scaduto (0 -> deny sempre).
         // da revisione: forma <> semantica — un bound oltre now()+2*GRACE_MS non e' producibile
         // da questa fetta: trattato come scaduto (0). Tolleranza 2*GRACE_MS per un
         // restart durante la grace. Fail-closed: bound assurdo = scaduto.
@@ -868,7 +868,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     }
   }
 
-  // --- superficie child (B5): register / refresh / recovery -------------------
+  // -- superficie child: register / refresh / recovery -------------------
   //
   // Tre metodi DISTINTI perche' i loro valori di ritorno non possono mentire
   // l'uno con l'altro: register puo' rispondere 'pending' (la cella non e'
@@ -877,13 +877,13 @@ function handleChallengeProof(cellId, entry, socket, msg) {
   // un proof scaduto da poco. Un metodo unico costringerebbe 'refresh' a un
   // valore di ritorno che mente in uno dei due casi.
   //
-  // B2: incarnationId e' PER-REGISTRATION, mai globale — il register di una
+  // IncarnationId e' PER-REGISTRATION, mai globale — il register di una
   // cella crea la propria incarnazione e non tocca le altre. Le registration
   // vivono in memoria e NON sopravvivono al restart del processo (coerente col
-  // fail-closed R3.3.1 del lease): dopo un restart del server il child
-  // re-registra (nuova incarnazione).
+  // fail-closed lease model): after a server restart the child
+  // re-registers (new incarnation).
   //
-  // B3: l'unita' dell'attempt e' la PRESENTAZIONE di recovery, non la
+  // L'unita' dell'attempt e' la PRESENTAZIONE di recovery, non la
   // connessione — una connessione puo' portare piu' presentazioni, e contare
   // connessioni conterebbe la cosa sbagliata. Ogni presentazione (anche negata)
   // consuma un attempt della propria registration; oltre il cap la
@@ -891,7 +891,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
   const childRegs = new Map(); // cellId -> { incarnationId, createdAt, lastAt, recoveryAttempts }
   const RECOVERY_ATTEMPT_CAP = 8;
   // Finestre del child, derivate dalle misure del lease:
-  //   - un proof vive PROOF_TTL_MS (B8: 60s) dall'ultimo refresh;
+  // Un proof vive PROOF_TTL_MS (60s) dall'ultimo refresh;
   //   - il recovery accetta un proof scaduto da meno di una grace (L.GRACE_MS):
   //     il detentore ha saltato i refresh, non e' stato sostituito;
   //   - quindi la registration e' viva fino a lastAt + PROOF_TTL_MS + GRACE_MS.
@@ -914,7 +914,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
     if (!validCellId(cellId)) return { status: 'denied', reason: 'cellId' };
     if (!cells.has(cellId)) {
       // La cella non e' (ancora) tracciata dal lease del supervisore: il join e'
-      // pendente. Solo register puo' rispondere cosi' (B5).
+      // Pendente. Solo register puo' rispondere cosi'.
       return { status: 'pending', retryAfterMs: L.REFRESH_MS };
     }
     const launchSubject = cells.get(cellId) && cells.get(cellId).subject;
@@ -982,7 +982,7 @@ function handleChallengeProof(cellId, entry, socket, msg) {
   function childRecovery(cellId, proof) {
     const reg = childRegs.get(cellId);
     if (!reg) return { status: 'no-registration' };
-    // B3: la presentazione conta PRIMA dell'esito — anche un tentativo negato
+    // La presentazione conta PRIMA dell'esito — anche un tentativo negato
     // consuma un attempt della registration.
     reg.recoveryAttempts += 1;
     if (reg.recoveryAttempts > RECOVERY_ATTEMPT_CAP) {

package/lib/fleet/cell-lease.js

@@ -2,31 +2,31 @@
 
 // Pure state transitions for the supervisor lease of a Live host cell.
 //
-// Contratto rev12 R3 + rev13 S3 + rev22. Il canale lease e' la connessione UDS
+// Contratto rev12 + rev13 + rev22. Il canale lease e' la connessione UDS
 // accettata col nonce one-shot del launch-broker che RESTA APERTA dopo il frame
-// payload (R3.1.1); dopo un EOF il supervisore si riconnette a un endpoint
-// stabile (R3.3.2). Qui vivono SOLO le transizioni di stato del lease: i side
-// effect (socket, timer, EOF handling) stanno nel LeaseManager e nei caller.
+// payload; after an EOF the supervisor reconnects to a stable endpoint.
+// Here live ONLY the lease state transitions: the side
+// effects (socket, timer, EOF handling) live in the LeaseManager and the callers.
 // Modello speculare a lib/nodes/reverse-rotation.js (clone + arg validation),
 // cosi' i casi crash/replay sono espliciti e testabili senza socket.
 //
 // Invarianti normativi ribaditi nel codice:
-//  - EOF arma UNA sola transizione monotona Live -> Grace (R3.1.3); la deadline
-//    e' non estendibile: un secondo armGrace su un lease in Grace e' no-op.
+//  - EOF arms a SINGLE monotonic Live -> Grace transition; the deadline
+//    is not extendable: a second armGrace on a Grace lease is a no-op.
 //  - Nessuna operazione riporta in Live un lease gia' in Grace: refresh e armGrace
 //    non cambiano lo stato di un lease in Grace. Solo reattach crea un lease NUOVO.
-//  - reattach (R3.3.4) produce un lease con leaseId NUOVO e STESSA identita'
-//    cellId+launchEpoch (la generation puo' avanzare). Non e' la resurrezione del
-//    lease precedente: il vecchio lease resta nella sua grace, la monotonia
-//    per-lease resta intatta e la vecchia deadline diventa irrilevante.
-//  - Oltre la grace il reconnect e' rifiutato (R3.3.5): reattach di un lease
-//    scaduto restituisce null.
+//  - reattach produces a lease with a NEW leaseId and the SAME identity
+//    cellId+launchEpoch (the generation may advance). It is not the resurrection
+//    of the previous lease: the old lease stays in its grace, the per-lease
+//    monotonicity stays intact and the old deadline becomes irrelevant.
+//  - Past the grace the reconnect is refused: reattach of an expired
+//    lease returns null.
 
 const crypto = require('node:crypto');
 
-const GRACE_MS = 60_000;             // R3.2: grace 60s dall'EOF, non estendibile
-const REFRESH_MS = 20_000;           // R3.2: cadenza refresh 20s (heartbeat lato supervisore)
-const RECONNECT_CADENCE_MS = 20_000; // rev13 S3.3: >=2 tentativi strettamente dentro la grace
+const GRACE_MS = 60_000;             // grace: 60s from EOF, not extendable
+const REFRESH_MS = 20_000;           // refresh cadence 20s (supervisor-side heartbeat)
+const RECONNECT_CADENCE_MS = 20_000; // >=2 attempts strictly inside the grace window
 
 function isInt(v) { return Number.isSafeInteger(v); }
 function validId(v, max = 128) { return typeof v === 'string' && v.length > 0 && v.length <= max; }
@@ -49,7 +49,7 @@ function openLease({ cellId, launchEpoch, generation, leaseId, now }) {
 }
 
 // EOF arma UNA sola transizione monotona Live -> Grace. Su un lease gia' in Grace
-// e' no-op (ritorna lo stesso lease): la deadline NON si estende (R3.1.3).
+// is a no-op (returns the same lease): the deadline is NOT extendable.
 function armGrace(lease, { now } = {}) {
   if (!lease || !isInt(now)) return null;
   if (lease.state === 'grace') return lease;
@@ -61,16 +61,16 @@ function armGrace(lease, { now } = {}) {
 }
 
 // Refresh: heartbeat lato supervisore (cad 20s). Aggiorna lastRefreshedAt. NON
-// cambia state e NON riporta in Live un lease in Grace (R3.1.3). Hook per la
-// rotazione del proof HMAC (fetta 2b); in 2a e' solo liveness applicativa + ack.
+// never changes state and never brings a Grace lease back to Live. Hook for the
+// HMAC proof rotation; today it is application liveness + ack only.
 function refresh(lease, { now } = {}) {
   if (!lease || !isInt(now)) return null;
   return { ...lease, lastRefreshedAt: now };
 }
 
-// Reconnect riuscito (R3.3.4): lease NUOVO (leaseId nuovo), STESSA identita'
-// cellId+launchEpoch (la generation puo' avanzare), state Live. R3.3.5: oltre la
-// grace il reconnect e' rifiutato -> null. Il vecchio lease resta nella sua grace.
+// Successful reconnect: NEW lease (new leaseId), SAME identity
+// cellId+launchEpoch (the generation may advance), state Live. Past the
+// grace the reconnect is refused -> null. The old lease stays in its grace.
 function reattach(lease, { leaseId, generation, now } = {}) {
   if (!lease || !validLeaseId(leaseId) || !isInt(generation) || generation < 0 || !isInt(now)) return null;
   if (lease.state === 'grace' && now >= lease.graceDeadline) return null;