Ridurre il surface area del toolkit e consolidare il contract runtime

[Gabrymi93]

🧾 Pull Request – DataCivicLab

🔗 Issue collegata

Closes #4

🎯 Contesto

Questa PR consolida il lavoro finale di hardening, riduzione del surface area e riallineamento del toolkit al ruolo corretto nell’ecosistema DataCivicLab.

Nel modello attuale:

• .github contiene policy condivise, community health e template GitHub
• dataciviclab è l’hub pubblico/minimale dell’organizzazione
• project-template è il template operativo dei repo dataset
• toolkit deve restare il motore tecnico della pipeline e la fonte dei contract runtime/config/path/output

La PR porta il toolkit a una forma più piccola, più leggibile e più coerente con il workflow reale dei repo dataset:

• run all
• validate all
• status
• inspect paths
• notebook locali che leggono output reali

⚙️ Cosa cambia

• riduce il codice non core:
  • rimossi shim deprecated di core
  • rimosso gen-sql
  • rimossi plugin peripheral/experimental
• chiarisce i confini del prodotto:
  • core runtime
  • advanced tooling
  • compatibility only
• rifattorizza i punti tecnicamente più densi:
  • clean.duckdb_read
  • clean.input_selection
  • clean.run
  • clean.validate
  • profile.raw
• rende più esplicito il contract runtime/output:
  • distinzione tra metadata.json, manifest.json, run records e inspect paths
  • naming separato per manifest RAW vs manifest standard di layer
• integra i marker pytest (core, advanced, compat) e documenta meglio la suite
• mantiene il branch finale coerente con project-template e col workflow canonico

📊 Impatto su dati / metodo / dashboard

Indicare se questa PR impatta:

• RAW
• CLEAN
• MART
• Dashboard
• Metodo
• Documentazione
• Bugfix
• Nessun impatto dati

Effetti su replicabilità e confrontabilità:

• migliora la replicabilità dei repo dataset perché rafforza il contract di runtime e output
• riduce la dipendenza da feature periferiche o frozen
• migliora la confrontabilità tra repo clonati dal template grazie a un contract più chiaro su path, metadata, manifest e run records
• non introduce logica dataset-specifica

🧪 QA Checklist

• Ho testato il codice / notebook
• Non rompe pipeline esistenti
• Naming coerente (snake_case, convenzioni Lab)
• Documentazione aggiornata
• Ho collegato l’issue corretta

Verifiche eseguite:

• py -3.14 -m pytest -q -p no:cacheprovider
• risultato: 146 passed
• py -3.14 -m ruff check --no-cache .
• risultato: pulito

📝 Note per i reviewer

Punti da guardare con attenzione:

• il toolkit ora ha un perimetro più stretto e più intenzionale; verificare che la riduzione del surface area sia coerente con il prodotto che vogliamo pubblicare
• inspect paths e il contract metadata / manifest / run records sono il punto chiave per notebook e repo dataset
• clean e profile.raw sono stati contenuti senza cambiare il contratto pubblico: il focus della review dovrebbe essere sulla chiarezza e sulla preservazione del comportamento
• la PR include sia semplificazione del prodotto sia chiarimento del posizionamento documentale del toolkit nell’ecosistema