Il ciclo di vita — Publish → Pull → Verify

Ogni artefatto — manifest, migrazioni, licenze plugin, contratto del tenant — segue lo stesso ciclo in tre fasi. Nessun nodo viene aggiornato distribuendo codice: gli artefatti fluiscono in un canale firmato e verificabile e si attivano a caldo.

1 · Publish (Control Plane)

Un admin (console o client API) pubblica una nuova versione del manifest:

POST /api/v1/admin/tenants/:id/manifests
Authorization: Bearer <admin-session>
{ "manifest": { ... }, "migrations": [ { "name": "001_init.sql", "sql": "..." } ] }

Cosa fa il Control Plane, in un’unica transazione:

1. Validazione — JSON Schema + meta.version strettamente maggiore di quella attiva (monotona, niente rollback via publish).
2. Packaging — manifest e migrazioni SQL sono impacchettati: il pacchetto è l’unità di distribuzione.
3. Firma — il pacchetto è firmato Ed25519 con la chiave privata del Control Plane. La privata non lascia mai il cloud; gli edge conoscono solo la pubblica.
4. Attivazione — is_active passa atomicamente alla nuova versione; le precedenti restano archiviate per audit.

Una subscription canceled non può pubblicare: ingest e sync continuano a funzionare, il manifest pull restituisce l’ultimo stato valido. Lo stato contrattuale è esso stesso distribuito come licenza tenant firmata.

2 · Pull (nodo Edge)

Ogni edge esegue un ciclo di sync periodico — ogni 30 secondi:

GET /api/v1/sync/manifest   →  manifest attivo + firma
GET /api/v1/sync/licenses   →  licenze plugin + licenza contrattuale del tenant
Authorization: Bearer <edge api_key>   (+ tenant_id)

Lo stesso ciclo drena l’outbox CDC (POST /api/v1/sync/ingest) e funge da heartbeat di flotta: il Control Plane registra last_poll_at a ogni chiamata autenticata. Un edge che tace è visibile in console entro un minuto.

Offline by design: se il Control Plane non risponde, il circuit breaker si apre, gli eventi restano nell’outbox locale e l’edge continua a eseguire l’ultimo manifest verificato. Nulla si perde — il sync riprende da solo.

3 · Verify & activate (nodo Edge)

Prima di eseguire qualsiasi cosa, l’edge verifica:

1. Firma — controllo Ed25519 contro la chiave pubblica pinnata. Firma invalida → pacchetto rifiutato, fail-closed, il manifest corrente continua a girare.
2. Versione — deve essere maggiore di quella installata.
3. Snapshot — snapshot automatico pre-migrazione delle tabelle coinvolte (schemi snap_*), così una migrazione errata è reversibile.
4. Migrazioni — applicate in transazione; qualsiasi errore fa rollback completo.
5. Hot swap — kernel.setManifest sostituisce il manifest attivo sullo stesso processo. Niente restart, niente downtime, nessuna sessione persa.

La licenza contrattuale del tenant è persistita localmente (sys_tenant_license) così l’edge applica il comportamento corretto — grace period offline incluso — anche da disconnesso.

Il quadro completo

 Dev/admin ──publish──▶ Control Plane ──firma──▶ pacchetto firmato
                                                       │
 edge ◀──pull ogni 30s── canale TLS ◀───────────────────┘
   │
   ├─ verifica firma (Ed25519) ──fail──▶ rifiuta, continua a girare
   ├─ snapshot → migrazioni (tx) ──fail──▶ rollback
   └─ hot swap manifest ──▶ nuova versione live, zero downtime

Due verticali di riferimento — un POS retail e un field service con work order — girano oggi sullo stesso engine attraverso esattamente questo ciclo.