Descrizione
Storage enterprise chiave-valore persistente scoped per workflow — la primitiva per implementare workflow stateful che devono ricordare dati cross-run tra esecuzioni successive del stesso workflow (cursor di paginazione di sync incrementali, contatori di retry, flag di "già processato" per idempotency, baseline KPI per detection di drift, timestamp di "ultima esecuzione" per cron skip-if-recent logic). Implementazione robusta su SQLite per-tenant del runtime, table dedicata `workflow_memory` con isolation rigorosa per workflow_id — workflow diversi NON si vedono tra loro (gli engineer principle di least privilege + memoria privata per workflow per evitare leak di state tra contesti separati e comportamenti emergenti debugging-difficili). Cinque operazioni atomiche coprono tutti i pattern stateful necessari: (1) get — legge il valore associato a una key; se la key non esiste ritorna value=null ed exists=false (pattern safe check-before-use), oppure il valore di default se configurato (usedDefault=true); (2) set — scrive (o sovrascrive se esiste) il valore della key, valore può essere qualsiasi JSON serializzabile (string, number, boolean, array, object nested fino a 1MB cap per safety); (3) append — concatena il valore a una stringa esistente con un separator configurabile (default newline), crea la key se non esiste (pattern naturale per log accumulato di righe); (4) delete — rimuove la key (idempotent: delete su key inesistente = no-op); (5) list — restituisce l'elenco delle key esistenti per il workflow corrente, con filtro pattern glob opzionale (es. "cursor:*" → tutte le key che iniziano con "cursor:"; * = molti char, ? = un char) (output keys[] + count + pattern). TTL opzionale per auto-cleanup: ogni key può avere un TTL in secondi; la pulizia è LAZY al prossimo get (una key scaduta viene cancellata e ritorna exists=false) — pattern utile per cache time-limited (es. "deduplica notify per 24h" → key con TTL 86400s) senza dover gestire manualmente la cleanup logic. Concurrency: le operazioni sono atomic (SQLite transaction per write), in caso di concurrent run dello stesso workflow (es. due trigger_webhook simultanei), le scritture sono serialized — no race condition su counter increment (l'idiom get → modify → set è race-prone, raccomandato pattern dedicated atomic increment se servisse). Output: { value, exists, updatedAt, expiresAt (timestamp scadenza o null), operation, usedDefault (get), oldValue e changed (set, per audit del cambio), keys[] + count + pattern (list) }. Use case: memorizzare cursor di paginazione di una sync incrementale (es. "last_synced_at" per next iteration del cron, evita ri-fetch dei dati già processati); contatore tentativi retry distribuito su run cron schedulati (retry_count++ ogni fail, reset al success); flag "già notificato" per evitare doppi alert su stesso evento ricorrente (key "alerted:incident:XYZ" con TTL 24h); timestamp ultima esecuzione per cron skip-if-recent logic (se < 5min fa, skip questo tick); budget spese API mensili (cumulative cost tracking per quota enforcement custom oltre quelle del piano); accumulo di list di errori per batch summary email digest a fine giornata.