colscan 0.2.0__py3-none-any.whl

colscan/__init__.py

@@ -0,0 +1,20 @@
+"""colscan — tell what is inside a table's columns, offline, with rules only.
+
+Public API:
+
+    from colscan import scan_column, scan_table
+
+`scan_column(values, name=None)` classifies one column; `scan_table(source)`
+opens a CSV, a Parquet file or a database table and classifies every column.
+
+Everything here is deterministic: a value is an IBAN because it passes the mod-97
+check, not because a model thinks so. Nothing is sent anywhere.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .scan import scan_column, scan_table  # noqa: E402,F401
+
+__all__ = ["scan_column", "scan_table", "__version__"]

colscan/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m colscan …`, for whoever cannot put a console script on PATH.
+
+Same entry point as the `colscan` command: a locked-down machine where `pip
+install --user` puts the script somewhere that is not in PATH is exactly the kind
+of machine this tool is for.
+"""
+
+from .cli import main
+
+raise SystemExit(main())

colscan/_engine/PROVENANCE.json

@@ -0,0 +1,20 @@
+{
+  "files": {
+    "colname.py": {
+      "commit": "11651c91b579ae7c3d00eefb71e78f1af7a5b7e8",
+      "sha256": "b4c7ce39025926eed19edcdb7ac0593993916752b000d724e74cf011128d881b"
+    },
+    "taxonomy.py": {
+      "commit": "f3fe522b09244d013d59de7ebd5a6af38a143de1",
+      "sha256": "b2c2c387e97edbb4d471c702da25c8ac9072bb9856f7eff527c6ad344e0e8938"
+    },
+    "validators.py": {
+      "commit": "c42f863d42b4f1d20ffa3230e65e3e7f6d1e1937",
+      "sha256": "c4559e6b726e223756680505b8db2513d2c9b8db35448ce45a7dac05e4027b07"
+    },
+    "validators_it.py": {
+      "commit": "11651c91b579ae7c3d00eefb71e78f1af7a5b7e8",
+      "sha256": "9a13f858896a838178a7bf2adf4218b51361bafb788ba83a92eed6da70345b98"
+    }
+  }
+}

colscan/_engine/__init__.py

@@ -0,0 +1,7 @@
+"""Vendored deterministic engine — generated by tools/sync_engine.py.
+
+Do not edit these files here: edit backend/colscan/ in the dbtool-platform repo
+and re-run the sync script. `PROVENANCE.json` records the source commit and the
+sha256 of every file, and `tools/sync_engine.py` (run by the test suite) fails if
+the copy drifts from the backend.
+"""

colscan/_engine/colname.py

@@ -0,0 +1,276 @@
+# ---------------------------------------------------------------------------
+# VENDORED FILE — DO NOT EDIT HERE.
+# Source of truth: backend/colscan/colname.py in the private repo
+# sheppard94g/dbtool-platform, commit 11651c91b579ae7c3d00eefb71e78f1af7a5b7e8.
+# Regenerate with: python tools/sync_engine.py --write
+# ---------------------------------------------------------------------------
+"""Canale sul NOME della colonna.
+
+Perché esiste, con la prova. Alla prima misura su 190 colonne di open data veri
+il sistema a sole celle sbagliava così:
+
+    measurement  → sequential_id   18 colonne
+    enum_code    → sequential_id   22 colonne
+
+Non è un difetto del modello: è che l'informazione **non è nella cella**. Nelle
+tabelle vere l'unità di misura sta nell'intestazione (`superficie_mq`,
+`consumo_kwh`, `importo_euro`) e la cella contiene `1234`. Nessun classificatore
+di celle, per quanto addestrato, può decidere se `1234` è una superficie, un
+codice interno o una chiave: l'informazione è stata separata dal dato a monte,
+da chi ha progettato la tabella.
+
+Come è costruito, e perché non è una rete. Un lessico esplicito è **verificabile
+da chi firma il registro dei trattamenti**: se lo strumento dice "questa colonna
+contiene codici fiscali", il DPO può leggere la regola che l'ha detto. In uno
+strumento di conformità questo vale più di qualche punto di accuratezza.
+
+La cautela che rende il tutto onesto: **il nome non può inventare un tipo
+incompatibile con i valori osservati.** Se l'intestazione dice `nome` ma la
+colonna contiene IBAN, vincono gli IBAN. Il nome può promuovere un tipo solo se
+la FORMA delle celle è compatibile — è la contromisura al rischio, dichiarato
+nello spec, che il sistema impari a leggere solo l'etichetta e resti cieco sui
+dati (che è poi il caso `f_12`, quello per cui il prodotto esiste).
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+# Forma grossolana delle celle: serve solo a dire se una promozione da nome è
+# plausibile. Volutamente a maglie larghe.
+FORME = {
+    "numerico": {"sequential_id", "amount", "measurement", "year", "coordinate",
+                 "postcode", "phone", "national_id", "boolean", "gender_label"},
+    "codice": {"enum_code", "fiscal_code_it", "vat_number", "iban", "bic",
+               "credit_card", "uuid", "hash_hex", "icd_code", "atc_code",
+               "country_code", "currency_code", "national_id", "postcode",
+               "mac_address", "boolean", "gender_label", "sequential_id"},
+    "testo": {"person_name_full", "person_given", "person_surname", "city",
+              "company_name", "institution_name", "street_address", "free_text",
+              "country_name", "region_admin", "job_title", "legal_form",
+              "gender_label", "enum_code"},
+    "misto": set(),   # url, email, path… hanno già regole proprie
+}
+
+
+def forma_di(valori: list[str]) -> str:
+    """Forma grossolana dei valori, per decidere se una promozione da nome è plausibile.
+
+    ⚠️ La versione precedente aveva un difetto che annullava il canale proprio
+    dove serviva di più: classificava come CODICE qualunque valore senza spazi e
+    sotto i 24 caratteri. Ma `Milano`, `Roma`, `Rossi`, `Verdi` sono esattamente
+    così — quindi una colonna di città risultava «codice», `city` non è
+    compatibile con «codice», e il suggerimento dell'intestazione `Comune`
+    veniva **scartato**. Risultato: la colonna finiva `person_surname`, che è un
+    tipo personale, e gonfiava i falsi allarmi sui dati personali.
+
+    La discriminante giusta non è la lunghezza ma la COMPOSIZIONE: una parola di
+    sole lettere è testo anche se corta; un codice contiene cifre, oppure è una
+    sigla breve tutta maiuscola.
+
+    ⚠️ Secondo difetto, stessa famiglia del primo e misurato sulle anagrafiche
+    italiane, dove i cognomi si scrivono TUTTI MAIUSCOLI. `ROSSI`, `RUSSO`,
+    `GRECO`, `CONTI`, `GALLO` sono cinque lettere maiuscole, cioè la definizione
+    di "sigla breve" data qui sopra: su dieci cognomi veri sei finivano fra i
+    codici e la colonna risultava «codice». Con `person_surname` incompatibile
+    con «codice», il suggerimento dell'intestazione `Cognome` veniva scartato di
+    nuovo — lo stesso guasto che questa funzione dichiara di aver corretto, sulla
+    forma più frequente del paese.
+    Una parola di cinque lettere maiuscole è però ambigua per davvero (`ACEM` è
+    una sigla, `ROSSI` un cognome): quindi ora **non vota**, e decidono i valori
+    non ambigui. Se sono ambigui tutti — una colonna di sole sigle brevi — vale
+    ancora «codice», che era il comportamento giusto per quel caso.
+    """
+    if not valori:
+        return "misto"
+    n_num = n_cod = n_txt = n_amb = 0
+    for v in valori[:200]:
+        s = v.strip()
+        if not s:
+            continue
+        if re.fullmatch(r"[-+]?\d+([.,]\d+)?", s):
+            n_num += 1
+        elif re.fullmatch(r"[^\W\d_][\w'’\-. ]*", s, re.UNICODE) and not any(c.isdigit() for c in s):
+            # sole lettere (con spazi, apostrofi, trattini): è testo, corto o lungo
+            # che sia — a meno che non sia una sigla breve tutta maiuscola, che è
+            # indistinguibile da un cognome maiuscolo e quindi si astiene
+            if len(s) <= 5 and s.isupper():
+                n_amb += 1
+            else:
+                n_txt += 1
+        else:
+            n_cod += 1
+    deciding = n_num + n_cod + n_txt
+    tot = max(deciding, 1)
+    if n_num / tot > 0.7:
+        return "numerico"
+    if n_txt / tot > 0.5:
+        return "testo"
+    if n_cod / tot > 0.5:
+        return "codice"
+    if n_amb and deciding == 0:
+        return "codice"
+    return "misto"
+
+
+# Lessico multilingua: parola chiave -> tipo. Le chiavi sono confrontate sui
+# TOKEN del nome normalizzato, non per sottostringa, altrimenti `id` pesca
+# dentro `identificativo`, `residenza` e mezza tabella.
+LESSICO: dict[str, tuple[str, ...]] = {
+    "person_name_full": ("nominativo", "nome_cognome", "nomecognome", "fullname",
+                         "full_name", "denominazione_persona", "intestatario",
+                         "richiedente", "titolare", "contatto", "persona"),
+    # ⚠️ QUI SI SOTTRAE, NON SI AGGIUNGE, ed è la correzione più redditizia del
+    # lessico. Misurato su 35.955 intestazioni reali: `nom*` mappato su
+    # `person_surname` dichiarava COGNOMI **647 colonne su 268 tabelle**, e quasi
+    # nessuna lo era. In francese e in catalano `nom` è il nome *di una cosa*, e
+    # `nom_<entità>` è lo schema di denominazione standard dei portali francesi e
+    # barcellonesi: `Nom_Barri` = "la Trinitat Nova", `nom_voie` = "Rue de
+    # Normandie", `nom_commune` = "Le Grès".
+    # Gemello opposto: in spagnolo `nombre` è "nome", ma in **francese è
+    # "numero"** — `nombre_de_reponses` con valori 58, 351 finiva fra i nomi
+    # propri. Due lingue, la stessa stringa, due significati incompatibili.
+    # La guardia sulla forma delle celle non ferma nulla, perché `person_surname`
+    # è compatibile con la forma `testo`: l'unico rimedio è togliere la voce.
+    # `prenom` resta (è inequivocabile), `nom_de_famille` copre il cognome francese.
+    "person_given": ("nome", "firstname", "first_name", "givenname", "given_name",
+                     "prenom", "prénom", "vorname"),
+    "person_surname": ("cognome", "lastname", "last_name", "surname", "familyname",
+                       "nom_de_famille", "nom_famille", "nachname", "apellido",
+                       "apellidos", "cognom", "cognoms"),
+    "gender_label": ("sesso", "genere", "gender", "sex", "geschlecht", "sexe"),
+    "fiscal_code_it": ("codice_fiscale", "codicefiscale", "cod_fisc", "codfisc",
+                       "cf", "c_f", "cfisc"),
+    "vat_number": ("partita_iva", "partitaiva", "piva", "p_iva", "vat", "iva",
+                   "ust_id", "umsatzsteuer", "nif", "cif"),
+    "iban": ("iban", "conto_corrente", "coordinate_bancarie"),
+    "email": ("email", "e_mail", "mail", "pec", "posta_elettronica", "indirizzo_mail",
+              "courriel"),
+    "phone": ("telefono", "tel", "cellulare", "cell", "fax", "phone", "telefon",
+              "recapito_telefonico", "numero_telefono", "tel_fax"),
+    "street_address": ("indirizzo", "via", "ubicazione", "address", "strasse",
+                       "adresse", "sede", "domicilio", "residenza", "toponimo",
+                       "denominazione_via", "localizzazione", "strasse", "straße",
+                       "nom_voie", "nom_carrer", "nom_rue", "carrer", "voie",
+                       "adreca", "direccion"),
+    "city": ("citta", "comune", "city", "localita", "paese_citta", "stadt",
+             "ville", "municipio", "town", "comune_sede", "gemeinde", "ort",
+             "nom_commune", "nom_de_la_commune", "nom_com", "commune",
+             "ciudad", "poblacio", "municipi"),
+    "postcode": ("cap", "codice_postale", "zip", "postcode", "postal_code", "plz"),
+    "country_name": ("nazione", "paese", "stato", "country", "land", "pays",
+                     "nazionalita", "cittadinanza"),
+    "country_code": ("cod_nazione", "country_code", "iso_paese", "sigla_nazione"),
+    "region_admin": ("regione", "provincia", "prov", "sigla_provincia", "distretto",
+                     "region", "bundesland", "departement", "circoscrizione",
+                     "municipio_zona", "area_statistica", "quartiere", "zona",
+                     "sigla_prov", "provincia_sigla", "kreis", "landkreis",
+                     "bezirk", "nom_reg", "nom_dept", "nom_dep", "nom_districte",
+                     "nom_barri", "nom_epci", "districte", "barri", "departement",
+                     "comarca", "provincia_nome"),
+    "company_name": ("ragione_sociale", "ragionesociale", "denominazione",
+                     "impresa", "azienda", "ditta", "societa", "company",
+                     "firmenname", "raison_sociale", "beneficiario", "fornitore",
+                     "operatore_economico", "aggiudicatario", "insegna"),
+    "institution_name": ("ente", "istituto", "istituzione", "struttura", "scuola",
+                         "universita", "ospedale", "amministrazione", "affiliazione",
+                         "organizzazione", "organization", "einrichtung",
+                         "nom_etablissement", "nom_equipament", "nom_du_lieu",
+                         "equipament", "etablissement", "denominazione_ente"),
+    "job_title": ("qualifica", "mansione", "ruolo", "incarico", "carica",
+                  "professione", "job_title", "position", "funzione"),
+    "legal_form": ("forma_giuridica", "natura_giuridica", "tipo_societa",
+                   "legal_form", "rechtsform"),
+    "amount": ("importo", "valore", "costo", "prezzo", "spesa", "compenso",
+               "ammontare", "totale", "euro", "imponibile", "budget", "amount",
+               "betrag", "montant", "impegno", "pagato", "stanziamento",
+               "entrate", "uscite", "saldo", "retribuzione", "stipendio"),
+    "currency_code": ("valuta", "divisa", "currency"),
+    "date": ("data", "date", "datum", "giorno", "data_nascita", "datanascita",
+             "data_inizio", "data_fine", "scadenza", "decorrenza", "dat"),
+    "datetime": ("timestamp", "data_ora", "datetime", "rilevazione", "ora"),
+    "year": ("anno", "year", "esercizio", "annualita", "jahr", "annee"),
+    "url": ("url", "sito", "sito_web", "link", "web", "homepage", "pagina"),
+    # Il canale era capovolto: riconosceva `nord` ed `est` — che nelle tavole
+    # statistiche italiane sono MACRO-AREE (86 tabelle), non assi cartesiani — e
+    # non conosceva `latitude` e `longitude`, presenti in 88 tabelle ciascuna.
+    "coordinate": ("latitudine", "longitudine", "latitude", "longitude", "lat",
+                   "lon", "lng", "long", "coordinata", "coord", "coordinates",
+                   "x_coord", "y_coord", "breitengrad", "laengengrad",
+                   "geo_point", "geo_point_2d", "punto_geo"),
+    "measurement": ("superficie", "area", "lunghezza", "larghezza", "altezza",
+                    "peso", "volume", "distanza", "consumo", "potenza", "quantita",
+                    "temperatura", "concentrazione", "valore_misura", "mq", "kmq",
+                    "mc", "kwh", "kw", "metri", "posti", "capienza", "numero_posti",
+                    "abitanti", "popolazione", "densita", "perimetro",
+                    "anzahl", "ergebnis", "wert", "menge", "flaeche", "fläche",
+                    "hoehe", "höhe", "gewicht", "verbrauch", "nombre_de",
+                    "nombre_d", "effectif", "effectifs", "cantidad"),
+    "sequential_id": ("id", "codice_id", "progressivo", "numero", "num", "n",
+                      "chiave", "key", "pk", "record", "riga", "seq", "objectid",
+                      "fid", "gid", "cod_id"),
+    # `code`, `type`, `label` valgono ~3.270 colonne su ~700 tabelle: erano
+    # coperte solo nelle forme italiane. `name` NON entra qui e NON va su
+    # `person_*`: nei portali è il nome di una cosa, esattamente come `nom`.
+    "enum_code": ("code", "type", "label", "codigo", "codi", "tipus", "art",
+                  "kategorie", "klasse", "schluessel", "schlüssel", "merkmal",
+                  "auspraegung", "ausprägung", "statistik",
+                  "codice", "cod", "sigla", "tipo", "tipologia", "categoria",
+                  "classe", "stato", "status", "livello", "grado", "settore",
+                  "ateco", "cpv", "capitolo", "voce", "gruppo"),
+    "boolean": ("flag", "attivo", "abilitato", "presente", "disponibile",
+                "is_", "ha_", "si_no"),
+    "icd_code": ("diagnosi", "icd", "patologia", "codice_diagnosi"),
+    "atc_code": ("atc", "farmaco", "principio_attivo"),
+    "free_text": ("beschreibung", "bezeichnung", "bemerkung", "hinweis",
+                  "description", "descripcion", "descripcio", "commentaire",
+                  "note", "descrizione", "descr", "oggetto", "annotazioni",
+                  "commento", "osservazioni", "motivazione", "dettaglio",
+                  "testo", "avvertenze", "note_agg"),
+}
+
+# indice inverso token -> tipi
+_IDX: dict[str, list[str]] = {}
+for _t, _kk in LESSICO.items():
+    for _k in _kk:
+        _IDX.setdefault(_k, []).append(_t)
+
+
+def normalizza(nome: str) -> list[str]:
+    s = unicodedata.normalize("NFKD", str(nome or ""))
+    s = "".join(c for c in s if not unicodedata.combining(c)).casefold()
+    s = re.sub(r"[^a-z0-9]+", "_", s).strip("_")
+    if not s:
+        return []
+    tok = [t for t in s.split("_") if t]
+    # oltre ai token singoli, le coppie adiacenti: `data_nascita`, `ragione_sociale`
+    coppie = ["_".join(tok[i:i + 2]) for i in range(len(tok) - 1)]
+    triple = ["_".join(tok[i:i + 3]) for i in range(len(tok) - 2)]
+    return [s] + triple + coppie + tok
+
+
+def prior(nome: str) -> dict[str, float]:
+    """Punteggio per tipo a partire dal nome della colonna.
+
+    Le corrispondenze più lunghe pesano di più: `data_nascita` deve battere
+    `data`, e `codice_fiscale` deve battere `codice`.
+    """
+    out: dict[str, float] = {}
+    if not nome:
+        return out
+    for frammento in normalizza(nome):
+        for t in _IDX.get(frammento, ()):
+            peso = 1.0 + 0.6 * frammento.count("_")
+            out[t] = max(out.get(t, 0.0), peso)
+    if not out:
+        return out
+    top = max(out.values())
+    return {k: v / top for k, v in out.items()}
+
+
+def compatibile(tipo: str, forma: str) -> bool:
+    """Il nome può promuovere `tipo` solo se la forma delle celle lo consente."""
+    if forma == "misto":
+        return True
+    return tipo in FORME.get(forma, set())

colscan/_engine/taxonomy.py

@@ -0,0 +1,157 @@
+# ---------------------------------------------------------------------------
+# VENDORED FILE — DO NOT EDIT HERE.
+# Source of truth: backend/colscan/taxonomy.py in the private repo
+# sheppard94g/dbtool-platform, commit f3fe522b09244d013d59de7ebd5a6af38a143de1.
+# Regenerate with: python tools/sync_engine.py --write
+# ---------------------------------------------------------------------------
+"""Tassonomia dei tipi semantici di cella per colscan.
+
+Un solo posto in cui i tipi sono definiti: generatori, validatori, addestramento
+e valutazione importano tutti da qui. Se un tipo non è in questa lista, non
+esiste — è la contromisura al rischio "la tassonomia esplode" dichiarato nello
+spec (docs/superpowers/specs/2026-08-16-column-classifier-design.md, §4).
+
+Ogni tipo dichiara:
+  family        famiglia di appartenenza (per il rendiconto aggregato)
+  personal      se un valore di questo tipo è di per sé un dato personale
+                (art. 4(1) GDPR) — vedi la nota sotto
+  special       se ricade nelle categorie particolari (art. 9 GDPR)
+  regular       se il tipo ha una forma verificabile in modo deterministico.
+                I tipi `regular=True` sono di competenza dei VALIDATORI, non
+                della rete: per loro una regola con cifra di controllo ha
+                precisione praticamente perfetta ed è spiegabile a un auditor.
+                La rete serve dove `regular=False`.
+
+NOTA sul campo `personal`. È una proprietà del *valore isolato*, non della
+colonna nel suo contesto: un IBAN è un dato personale se riferito a una persona
+fisica e non lo è se riferito a una società. Il campo qui dice "questo tipo può
+identificare o riferirsi a una persona fisica", cioè fa scattare la verifica, e
+NON è un giudizio giuridico. Lo strumento segnala; la qualificazione la fa chi
+tiene il registro dei trattamenti.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TypeSpec:
+    name: str
+    family: str
+    personal: bool
+    special: bool
+    regular: bool
+    desc: str
+
+
+_T = [
+    # ---- identity -----------------------------------------------------------
+    TypeSpec("person_name_full", "identity", True, False, False, "Nome e cognome insieme"),
+    TypeSpec("person_given", "identity", True, False, False, "Solo il nome proprio"),
+    TypeSpec("person_surname", "identity", True, False, False, "Solo il cognome"),
+    TypeSpec("gender_label", "identity", True, False, True, "M/F/maschio/female/1/2..."),
+    TypeSpec("fiscal_code_it", "identity", True, False, True, "Codice fiscale italiano"),
+    TypeSpec("national_id", "identity", True, False, True, "Documento/ID nazionale non italiano"),
+    # ---- contact ------------------------------------------------------------
+    TypeSpec("email", "contact", True, False, True, "Indirizzo email"),
+    TypeSpec("phone", "contact", True, False, True, "Numero di telefono"),
+    TypeSpec("street_address", "contact", True, False, False, "Via e civico"),
+    # Le anagrafiche vere separano spessissimo la via dal civico in due colonne
+    # (`Civico`, `CIVICO`, `civico`: 4 colonne su 700 nel banco reale). Senza
+    # questo tipo il civico cade in `sequential_id`, cioè in un tipo NON
+    # personale — e una colonna di civici accostata a una di vie è parte di un
+    # indirizzo, quindi dato personale. Era l'errore più costoso dei cinque.
+    TypeSpec("house_number", "contact", True, False, True, "Numero civico isolato"),
+    TypeSpec("city", "contact", False, False, False, "Nome di città"),
+    TypeSpec("postcode", "contact", False, False, True, "CAP / codice postale"),
+    TypeSpec("country_name", "contact", False, False, False, "Nome di paese"),
+    TypeSpec("country_code", "contact", False, False, True, "ISO 3166 alpha-2/3"),
+    TypeSpec("region_admin", "contact", False, False, False, "Regione/provincia/stato"),
+    # Continente e macro-area (ripartizione geografica) non sono una regione:
+    # confonderli fa sbagliare il livello di aggregazione a chi legge il dato.
+    # Vocabolario chiuso di qualche decina di voci, quindi competenza della regola.
+    TypeSpec("continent", "contact", False, False, True, "Continente o macro-area geografica"),
+    TypeSpec("coordinate", "contact", False, False, True, "Latitudine/longitudine"),
+    # ---- financial ----------------------------------------------------------
+    TypeSpec("iban", "financial", True, False, True, "IBAN (checksum mod-97)"),
+    TypeSpec("bic", "financial", False, False, True, "BIC/SWIFT"),
+    TypeSpec("credit_card", "financial", True, False, True, "Carta di pagamento (Luhn)"),
+    TypeSpec("vat_number", "financial", False, False, True, "Partita IVA / VAT"),
+    TypeSpec("amount", "financial", False, False, True, "Importo monetario"),
+    TypeSpec("currency_code", "financial", False, False, True, "ISO 4217"),
+    # ---- org ----------------------------------------------------------------
+    TypeSpec("company_name", "org", False, False, False, "Ragione sociale"),
+    TypeSpec("institution_name", "org", False, False, False, "Ente/istituzione/affiliazione"),
+    TypeSpec("job_title", "org", False, False, False, "Qualifica professionale"),
+    TypeSpec("legal_form", "org", False, False, False, "Forma giuridica (S.p.A., GmbH...)"),
+    # ---- health (art. 9) ----------------------------------------------------
+    TypeSpec("icd_code", "health", True, True, True, "Codice diagnosi ICD-9/ICD-10"),
+    TypeSpec("atc_code", "health", True, True, True, "Codice farmaco ATC"),
+    # ---- temporal -----------------------------------------------------------
+    TypeSpec("date", "temporal", False, False, True, "Data"),
+    TypeSpec("datetime", "temporal", False, False, True, "Data e ora"),
+    TypeSpec("year", "temporal", False, False, True, "Anno"),
+    # `2026-W33`, `2026Q3`, `2026-08`: un PERIODO, non un istante. In
+    # epidemiologia e nelle serie storiche è la chiave temporale normale (la
+    # colonna `year_week` del banco reale è settimana ISO). Chiamarlo `date`
+    # è un errore di semantica, non di formato: una data si ordina e si
+    # sottrae, un periodo si aggrega.
+    TypeSpec("period", "temporal", False, False, True, "Settimana ISO, trimestre, mese"),
+    # POI, farmacie, musei, sportelli: 7 colonne su 700 nel banco reale, una
+    # per giorno della settimana. Nessun tipo esistente ci si avvicinava.
+    TypeSpec("opening_hours", "temporal", False, False, True, "Orario di apertura"),
+    # ---- technical ----------------------------------------------------------
+    TypeSpec("url", "technical", False, False, True, "URL"),
+    TypeSpec("domain", "technical", False, False, True, "Nome a dominio"),
+    TypeSpec("ip_address", "technical", False, False, True, "IPv4 o IPv6"),
+    TypeSpec("mac_address", "technical", False, False, True, "Indirizzo MAC"),
+    TypeSpec("uuid", "technical", False, False, True, "UUID"),
+    TypeSpec("hash_hex", "technical", False, False, True, "Digest esadecimale"),
+    TypeSpec("sequential_id", "technical", False, False, True, "Contatore/chiave numerica"),
+    TypeSpec("enum_code", "technical", False, False, False, "Codice breve da vocabolario chiuso"),
+    # Il tipo che svuota la discarica. `enum_code` è il tipo più frequente del
+    # banco reale (174 colonne su 700) e ci finisce dentro tutto ciò che è
+    # "corto e non riconosciuto". Ma CIG, CUP, codice catastale, codice ISTAT,
+    # codice meccanografico, codice IPA e ATECO NON sono vocabolari chiusi
+    # arbitrari: hanno una forma propria e un elenco ufficiale pubblicato, cioè
+    # sono competenza dei validatori. Stessa famiglia di `enum_code` di
+    # proposito, perché è da lì che vengono e perché sbagliare fra i due resta
+    # un errore veniale nel rendiconto per famiglia.
+    TypeSpec("domain_identifier", "technical", False, False, True,
+             "Identificativo di dominio verificabile (CIG, CUP, catastale, ISTAT, ATECO…)"),
+    TypeSpec("boolean", "technical", False, False, True, "Vero/falso"),
+    TypeSpec("file_path", "technical", False, False, True, "Percorso o nome di file"),
+    # ---- other --------------------------------------------------------------
+    TypeSpec("measurement", "other", False, False, True, "Quantità con o senza unità"),
+    TypeSpec("free_text", "other", False, False, False, "Testo libero"),
+    TypeSpec("unknown", "other", False, False, False, "Vuoto, segnaposto o non riconosciuto"),
+]
+
+TYPES = {t.name: t for t in _T}
+LABELS = [t.name for t in _T]
+LABEL_TO_ID = {n: i for i, n in enumerate(LABELS)}
+N_LABELS = len(LABELS)
+
+FAMILIES = sorted({t.family for t in _T})
+REGULAR = [t.name for t in _T if t.regular]
+IRREGULAR = [t.name for t in _T if not t.regular]
+PERSONAL = [t.name for t in _T if t.personal]
+SPECIAL = [t.name for t in _T if t.special]
+
+# I tipi su cui si decide se il modello merita di esistere. Sui tipi `regular`
+# la linea di base deterministica vince per costruzione e va usata quella: un
+# modello che li reimpara spende settimane per peggiorare il risultato.
+DECIDING = [t for t in IRREGULAR if t != "unknown"]
+
+
+def describe() -> str:
+    out = [f"{N_LABELS} tipi, {len(FAMILIES)} famiglie",
+           f"  regolari (competenza dei validatori): {len(REGULAR)}",
+           f"  irregolari (competenza della rete):   {len(IRREGULAR)}",
+           f"  dato personale: {len(PERSONAL)} · categoria particolare art.9: {len(SPECIAL)}",
+           "", "Tipi su cui si giudica il modello (criterio di arresto):",
+           "  " + ", ".join(DECIDING)]
+    return "\n".join(out)
+
+
+if __name__ == "__main__":
+    print(describe())