Importazione, origine e condivisione

Importazione: cosa viene scritto, cosa non lo è mai

Importare un match, una posizione o un altro database aggiunge ciò che manca; non sostituisce ciò che è già presente.

Una posizione non è mai duplicata. È la sua identità — pedine, cubo, dadi, punteggio — a riconoscerla, mai il file da cui proviene: la stessa posizione incontrata in due match resta un’unica riga.
Importare un database rilegge tutto ciò che un’esportazione scrive. Le posizioni, con le loro analisi e i commenti, ma anche i match (partite e mosse comprese), i tornei con la loro Direzione e il loro Incontro, le bozze di trascrizione, gli alias, le collezioni, le lezioni e i mazzi Anki: vedi Unire un database. Nulla viene sovrascritto: un match già presente non viene ricopiato, un torneo con lo stesso nome riceve i match senza cambiare la data dell’evento (la sua data di ultima modifica avanza, poiché riceve nuovi match), un torneo che ha già la sua Direzione la conserva e resta fuori dall’Incontro importato, un match già archiviato in un altro torneo o in un altro posto del tabellone vi resta, e ciò che il database aveva già deciso resta deciso da esso. I tornei, le Direzioni, gli Incontri, le bozze di trascrizione e gli alias creati dall’importazione conservano le loro date d’origine; le collezioni, le lezioni e i mazzi Anki creati non le conservano.
Un’analisi per motore. eXtreme Gammon, GNUbg, BGBlitz e il valutatore integrato convivono sulla stessa posizione, e il pannello Analisi indica l’origine di ciascuna. Importarne una non cancella l’altra.
Un’analisi importata non viene mai ricalcolata. blunderDB la conserva così com’è, con la sua etichetta di livello (« 3-ply », « XG Roller++ », « Book »), le sue equity, i suoi errori, le sue probabilità e la fortuna del tiro. La regola è « una valutazione colma soltanto una lacuna »: l’analisi automatica dopo l’importazione visita solo le posizioni senza alcuna analisi, e la rianalisi delle analisi gammonNet obsolete lascia intatta ogni posizione che porta un’analisi importata (vedi Configurazione).
Reimportare un match già presente porta solo ciò che è più profondo. Il match è riconosciuto dal suo gioco (giocatori, lunghezza, dadi, mosse, cubo), non dalla sua analisi: nessun match, partita o mossa viene riscritto. Le marcature poste nel software d’origine vengono aggiunte, e un’analisi più profonda di quella salvata la sostituisce, posizione per posizione — una versione Roller++ dello stesso match sostituisce la versione 3-ply, qualunque sia l’ordine d’importazione; a profondità uguale o minore, l’analisi salvata resta. Reimportare lo stesso file quindi non riscrive nulla. Il rapporto d’importazione distingue i duplicati che non portavano nulla da quelli che hanno approfondito delle analisi. Da riga di comando, --skip-duplicates salta un duplicato senza riprenderne altro che le marcature. Un match troncato e poi completato (più partite) non è lo stesso match: viene importato come un secondo match.
Un’analisi illeggibile non impedisce l’importazione del match. Una decisione la cui analisi contiene un valore che non è un numero finito (NaN o infinito, presenti in alcuni file XG) viene importata senza quell’analisi; il resto del match entra normalmente, e il resoconto dell’importazione conta le decisioni interessate.
Un match già presente con altri nomi viene segnalato, mai unito. Le due impronte del match includono i nomi dei giocatori: «Martin A.» e «Alice Martin» fanno due match. L’importazione confronta anche i dadi (lunghezza, punteggio iniziale, dadi di ogni partita) e segnala, sotto la riga del file e nel rapporto, il match già presente nel database con altri nomi di cui ha i dadi. blunderdb repair --duplicates elenca queste coppie in un database esistente, insieme ai match troncati e alla loro versione più lunga.
Un nome noto con un’altra grafia viene registrato con il suo nome canonico. Un alias dice che «Martin A.» è un’altra grafia di «Alice Martin» (o che un nome di evento è un’altra grafia di un altro). All’importazione, i nomi dei giocatori e dell’evento vengono sostituiti dal loro nome canonico, e il match viene collocato nel torneo dell’evento canonico. Le impronte del match conservano i nomi del file: un file importato prima che il suo alias esistesse si riconosce quindi sempre. Un match i cui dadi sono quelli di un match presente nel database, e i cui nomi differiscono solo per alias noti, non è un secondo match: le sue analisi arricchiscono quello archiviato.

Gli alias si gestiscono nella scheda Corpus delle impostazioni: scegliere Giocatori o Eventi, inserire l’alias e il nome canonico, oppure togliere un alias dall’elenco. Proponi elenca i nomi che differiscono solo per maiuscole, accenti, punteggiatura o ordine delle parole; non viene applicato nulla senza un clic su Applica. La stessa scheda contiene la casella Ignora i duplicati all’importazione (l’equivalente di --skip-duplicates, per la sessione) e la ricerca dei duplicati probabili di un database esistente, quella di blunderdb repair --duplicates: ogni coppia è data dai suoi numeri di match, nulla viene unito. Sotto una coppia con gli stessi dadi, Crea questi alias registra con un clic gli alias di giocatore che farebbero nominare ai due match gli stessi giocatori, la grafia del match più recente diventando l’alias: una sola proposta quando un nome è comune a entrambi, altrimenti due — posto per posto, poi incrociata — tra cui si sceglie quella che dice chi è chi. Da riga di comando: blunderdb players alias e blunderdb events alias.

Una cartella si importa in parallelo. I file vengono letti su più core contemporaneamente e scritti a gruppi, sempre nell’ordine della cartella: i numeri dei match non dipendono dalla macchina. Un file identico, byte per byte, a un file già letto della stessa cartella non viene riletto: conta come duplicato. Annullare ferma l’importazione al gruppo in corso; ciò che era già scritto resta.
L’avanzamento si legge in posizioni al secondo. La finestra di importazione mostra la percentuale letta, la velocità, il tempo rimanente stimato e i conteggi in corso (importati, duplicati, in errore). Riduci la sposta nella barra di stato, da cui un’etichetta la riapre: l’importazione continua mentre lavori, e la finestra torna da sola con il rapporto alla fine. I primi cento errori sono elencati; i successivi sono contati, e il registro dell’applicazione li nomina tutti. Dalla riga di comando, blunderdb import --type batch mostra lo stesso avanzamento sullo standard error, e --format json lo restituisce nell’oggetto finale (progress).
Ogni file di un’importazione viene registrato, e un’importazione interrotta può essere ripresa. Per ogni file, il registro del lotto conserva il percorso, la dimensione, la data di modifica, l’impronta SHA-256 e il risultato: partita nuova (con il suo numero), duplicato (con la partita che lo copre), partita arricchita o errore (con il messaggio). Un’importazione annullata o interrotta si continua senza ripetere ciò che è già deciso: un file con lo stesso percorso, la stessa dimensione e la stessa data viene saltato senza essere letto; un file con lo stesso contenuto viene letto ma non analizzato; un file in errore viene riprovato. Nell’applicazione, la finestra di fine importazione elenca il registro (un file per riga, con il suo risultato e il messaggio di un errore; un file riprovato mostra il suo ultimo esito), e una riga che ha prodotto una partita la apre. Un’importazione annullata lascia la finestra aperta con il pulsante Riprendi. Da riga di comando, blunderdb import --type batch --dir <cartella> --resume <lotto> riprende il lotto il cui numero è stato mostrato all’avvio dell’importazione, e --format json restituisce il registro nell’oggetto finale (journal). Il server accetta resume nella richiesta di imports.batch e restituisce il registro tramite imports.files. Il registro è un dato dell’importazione: aprire o leggere un database non vi scrive nulla.
Un’importazione interrotta dall’arresto dell’applicazione si riprende dalla finestra. Il comando :resume elenca le importazioni che nulla ha terminato; si sceglie quella da continuare, poi si indicano di nuovo la cartella o i file, come --dir da riga di comando. Il registro del lotto decide che cosa non viene riletto.
Una cartella grande si importa in modalità massiva. A partire da 200 file, blunderDB scrive con una cache più grande e meno checkpoint. Se il database non contiene ancora alcuna posizione, va oltre: gli indici di ricerca vengono ricostruiti solo alla fine e le scritture non sono più sincronizzate sul disco. Un’interruzione di corrente durante un’importazione del genere può allora danneggiare il database: bisogna ricrearlo e rilanciare l’importazione. Un arresto brusco del programma, invece, lascia solo indici mancanti, che l’apertura successiva ricostruisce (il registro lo segnala).
Ciò che blunderDB non scrive mai: una fortuna ricalcolata — è letta dal file sorgente o resta sconosciuta — e un rollout che non ha lanciato lui stesso: i dati di rollout di un file .xg non vengono aperti. Sono memorizzati solo i rollout che blunderDB produce (Rollout), accanto all’analisi.

Pannello Metadati

Il pannello Metadati (CTRL-M) mostra le informazioni generali del database corrente: Utente, data di creazione (Creato), Versione dello schema e Descrizione. L’utente, la data e la descrizione si modificano sul posto e si salvano uscendo dal campo; la versione è in sola lettura. Accessibile anche tramite il comando meta.

Mostra inoltre, quando esiste, l’origine del database — vedere Distribuire un database: origine e password. Un database ordinario non mostra questa sezione.

Distribuire un database: origine e password

Un insegnante che distribuisce un database di posizioni dispone di due meccanismi, indipendenti l’uno dall’altro, entrambi facoltativi e scelti al momento dell’esportazione: contrassegnare il file con la sua origine e proteggerlo con una password.

Nota

Nessuno dei due tiene traccia di ciò che accade al file. blunderDB non registra nulla dal lato di chi riceve il database: aprire un database contrassegnato è esattamente come aprirne uno qualsiasi, e da nessuna parte viene annotato chi lo ha aperto, quando, né da dove proviene il suo contenuto.

Contrassegnare un database con la sua origine

La finestra di esportazione sta in una sola schermata: una fascia d’intestazione — il numero di posizioni esportate, Annulla ed Esporta… — poi una griglia, con una riga per famiglia e il suo conteggio. Questi conteggi sono esatti: sono letti dal server a ogni modifica di una casella, sulla stessa selezione dell’esportazione, e sono ciò che il file conterrà. Il file si sceglie per ultimo, dopo Esporta…; chiudere questa scelta senza un nome riporta alla griglia. Un indicatore di avanzamento si sovrappone poi per la durata della scrittura, la finestra si chiude da sola e il risultato compare nella barra di stato.

Nove punti meritano attenzione:

L’ambito: da un elenco — una ricerca, una raccolta — la riga Ambito sceglie tra l”Elenco corrente e l”Intera libreria. L’elenco corrente esporta le sue posizioni, e la riga Match propone soltanto quelli in cui queste posizioni sono state giocate; ogni match spuntato parte con tutte le sue posizioni. Dalla libreria, l’ambito è la libreria.
Intera libreria è l’esportazione del server e di export --type database: tutte le famiglie sono spuntate in partenza, i mazzi Anki con la loro cronologia di ripasso, e le trascrizioni in corso partono con il resto.
La sincronizzazione: con Intera libreria, la riga Sincronizzazione propone Solo le novità dall’ultima esportazione in questa cartella e il pulsante Scegli la cartella…. Il file non viene più richiesto: viene scritto in quella cartella con un nome nuovo, e i conteggi sono quelli di ciò che è nuovo (vedere Sincronizzare due macchine).
Un match parte con la sua bozza di trascrizione, sotto la casella Trascrizioni della riga Match, spuntata in partenza; i match che anche un torneo porta con sé. Una bozza che non ha ancora prodotto un match parte solo con l’intera libreria. Un match o una trascrizione legati a un video locale portano con sé soltanto il nome del file, senza la sua cartella, che il destinatario ricolloca sulla propria copia; un collegamento web parte così com’è. Anche il file da cui un match è stato importato parte solo con il suo nome.
Un match parte con gli alias dei suoi giocatori e del suo evento: la casella Alias, spuntata in partenza, fa seguire l’unione dei giocatori, e il destinatario legge un giocatore unito come uno solo. Un alias che non nomina nessuno dei match esportati resta da voi.
Una raccolta le cui posizioni non sono tutte nell’elenco arriva troncata. L’elenco delle raccolte mostra, per ciascuna, la parte coperta («12/40») e la segnala in rosso quando è parziale. La casella + le loro posizioni porta con sé le posizioni delle raccolte spuntate: quelle di un elenco fatto a mano, quelle che la query di una raccolta viva seleziona. Una raccolta viva la cui query indica righe che il file non contiene parte congelata: arriva come l’elenco che la sua query seleziona oggi, e l’elenco la segnala in rosso come «congelata» con una nota; spuntando + le loro posizioni resta viva.
Un torneo parte sempre con le sue partite: senza di esse il legame torneo–partita non esiste e il torneo arriverebbe vuoto. Selezionare un torneo porta con sé le sue partite, anche se la casella delle partite è deselezionata o limitata ad altre. Parte anche con la sua Direzione — registro, coppie, tavoli e collegamento delle partite esportate — e il suo Incontro parte non appena parte uno dei suoi tornei; la cartella di uscita della Direzione resta da voi. La Direzione si ritrova aprendo il file, oppure importandolo in un altro database.
Un mazzo Anki parte con le sue posizioni, come copia di studio nuova. La casella con la mia cronologia porta con sé anche lo stato di ogni carta e il registro dei suoi ripassi: un backup, o i vostri mazzi passati su un’altra macchina. È deselezionata per un elenco, spuntata per la libreria.
I filtri salvati non esportano contenuto ma le vostre ricerche, inutili nel database di qualcun altro; la casella è deselezionata per un elenco. Un filtro che designa una posizione, un match o un torneo tramite il suo numero viene rinumerato per il file; se ne designa uno che non parte, resta da voi.

Collezioni, lezioni, trascrizioni, mazzi Anki, alias e tornei partono con le date di creazione e di aggiunta che hanno da voi, non con la data dell’esportazione.

I campi Utente, Descrizione e Data di creazione descrivono il file prodotto; sono precompilati a partire dal database di origine.

Spuntare Filigrana fa comparire due campi:

Origine — che cos’è questo file e da dove viene, con parole vostre: «Corso di Jean Dupont — 12 marzo 2026». Questo campo è obbligatorio: finché è vuoto, è bordato di rosso e il pulsante di esportazione resta inattivo.
Nota, facoltativa — condizioni d’uso, indirizzo di contatto, la richiesta di non ridistribuire.

Il contrassegno è firmato con la tua identità di emittente. È quindi inalterabile e non falsificabile: nessuno può modificarlo né fabbricarne uno a tuo nome. Non è invece incancellabile: il file distribuito è un normale database SQLite e blunderDB è software libero. Non impedisce nulla: dice da dove viene il file.

I commenti che avete scritto sono firmati con la stessa identità: il destinatario vede che provengono da voi e se sono stati alterati lungo il percorso (vedi Pannello Commenti). Un commento che porta già la firma di un altro emittente la conserva. La barra di stato indica, al termine dell’esportazione, quanti dei vostri commenti sono stati firmati; un’esportazione senza contrassegno non ne firma nessuno.

Identità dell’emittente

I contrassegni sono firmati con la tua identità di emittente, creata da sé la prima volta che contrassegni un file; non c’è nulla da configurare. Appartiene a una persona e non a un database: tutti i tuoi file recano la stessa impronta pubblica, nella forma A3F1-9C24-7B05-E1D8.

Puoi comunicare questa impronta ai tuoi destinatari perché verifichino che un file proviene davvero da te. L’identità si sposta da un computer all’altro in un unico file (estensione .bdbid), eventualmente protetto da una passphrase. Questo file permette di firmare a tuo nome: non condividerlo.

Nelle impostazioni (icona a ingranaggio della barra degli strumenti), la scheda Identità dell’emittente mostra il tuo nome e la tua impronta e propone Salva identità…, Carica identità… e Rigenera….

Avvertimento

Rigenerare non revoca nulla. Un contrassegno incorpora la chiave pubblica che lo ha firmato: si verifica quindi per sempre, da sé. Se il tuo file di identità è trapelato, chi lo possiede potrà continuare a firmare con la tua vecchia impronta, e quei contrassegni resteranno validi.

Ciò che ti protegge dopo una fuga non è il software: è pubblicare la tua nuova impronta e disconoscere la vecchia presso i tuoi destinatari.

La rigenerazione sovrascrive la chiave attuale; blunderDB propone di salvarla prima di sostituirla.

Proteggere un database con una password

La password si digita mascherata, qui come all’apertura di un file protetto; l’icona a forma di occhio la mostra finché la si tiene premuta e la nasconde di nuovo appena la si rilascia.

Spuntare Password produce un file con estensione .dbx — anche se il nome scelto nella finestra di salvataggio termina con .db. Per aprirlo, usate la consueta apertura di database: la finestra di selezione accetta indifferentemente .db e .dbx. blunderDB chiede allora la password e installa accanto un database ordinario; dopo non viene più chiesto nulla.

La finestra propone di eliminare il file protetto una volta aperto: altrimenti si conserva lo stesso contenuto sotto due nomi. La casella non è selezionata per impostazione predefinita — il file protetto resta tuo se intendi trasmetterlo — e l’eliminazione avviene solo dopo un’apertura riuscita.

Avvertimento

La password protegge il trasporto del file, non il database. Impedisce a un terzo di aprire un file dimenticato in una cartella di download o un allegato inoltrato per errore. Non protegge da colui al quale hai dato la password.

La password viene verificata a ogni apertura, anche quando il file è già stato aperto in precedenza su quel computer.

Tecnicamente il database è cifrato con AES-256 in modalità GCM, con una chiave derivata dalla password tramite Argon2id (64 MiB di memoria, 3 passaggi, 4 thread) e un sale casuale proprio di ogni file. La modalità GCM autentica l’insieme: una password errata viene rilevata come tale, e così pure qualsiasi alterazione del file cifrato — non si ottiene mai in silenzio un database corrotto.

L’intestazione del file protetto resta in chiaro: la sua origine rimane leggibile senza la password.

Leggere l’origine di un file

Nell’applicazione, apri il file e mostra il pannello Metadati (comando meta). In cima al pannello compare una sezione Origine, in sola lettura, che indica ciò che è stato iscritto, da chi, quando, e lo stato della firma:

«✓ marcato da voi»: il file porta il vostro marchio, intatto;
«✓ firma verificata»: il contrassegno è intatto e proviene da un’altra chiave — confronta la sua impronta con quella che l’autore ti ha comunicato;
«⚠ firma non valida»: il documento è stato modificato o contraffatto.

Questa sezione non compare in un database ordinario.

Da riga di comando, blunderdb info --db file.db mostra l’origine e lo stato della firma, senza mai scrivere nel file. Il comando funziona anche su un file protetto, senza la password. Vedere CLI_USAGE.md per le opzioni --watermark e --password di export, nonché per identity e open.

Pubblicare una base per altri

Una base marcata si distribuisce come qualsiasi file — email, sito personale, chiavetta USB. blunderDB non fornisce alcun servizio: né deposito, né catalogo ospitato, né account. È una conseguenza diretta della sua concezione: dal lato di chi riceve un file non viene mai registrato nulla, e non ci sarebbe quindi nulla da comunicare a un servizio, anche se esistesse.

Ciò che rende una base pubblicata utilizzabile da un altro si riduce a quattro campi, tutti già presenti:

Utente — chi l’ha costituita, con il nome che vuoi veder citato.
Descrizione — che cosa contiene la base, in una frase che stia in un elenco: «240 decisioni di cubo al punteggio, commentate, livello intermedio».
Provenienza (della filigrana) — che cos’è questo file e per chi è stato prodotto. È la prima cosa che il destinatario legge nel pannello Metadati.
Impronta dell’emittente — pubblicala accanto al file, non dentro: è confrontandola che il destinatario verifica che il file viene da te e non da qualcuno che ha ripreso il tuo nome.

Una base pubblicata senza filigrana resta perfettamente utilizzabile; è semplicemente anonima, e il pannello Metadati non mostra allora alcuna sezione Provenienza.

Per far conoscere una base, la categoria Show and tell delle discussioni del deposito fa da elenco: è una lista tenuta da chi pubblica, non un servizio reso da blunderDB. Annunciarne una lì richiede il link, i quattro campi qui sopra e l’impronta.