prep-step/docs/history.md

Reverse engineering dei file Creo: stato e ripresa

Diario di passaggio di consegne per il lavoro sul formato dei .prt/.asm. Serve a chi riprende (anche in un'altra sessione) per sapere dove siamo, cosa è provato, da dove ripartire, senza rifare la strada. Il risultato del lavoro sta in formato-psb.md: qui c'è solo lo stato, le decisioni e i vicoli ciechi. Quando un punto si chiude, il contenuto va nel doc di formato e qui resta una riga.

Ultimo aggiornamento: 2026-11-10, ramo reverse-engineering-creo.

Stato in una riga

Il formato di serializzazione (PSB) è decodificato e tutte le sezioni in chiaro di 9253000117a.prt.35 si leggono fino all'ultimo byte con nome e valore di ogni campo; nessun valore è stato ancora confrontato con Creo, e tre cose bloccano "tutti i dati senza Creo" (vedi "Cosa manca").

Da non perdere

• Niente è committato. In sospeso: docs/formato-psb.md, docs/history.md, scripts/psb/, e le modifiche a CHANGELOG.md, docs/README.md, docs/architettura.md, docs/formato-prt-geometria.md.
• 9253000117a.prt.35 è nella root, non tracciato: è il campione di tutto il lavoro. Decidere se tenerlo nel repo (2 MB) o in raw/.
• scripts/psb/__pycache__/ va ignorato, non committato.
• docs/formato-prt-feature.md contiene byte NUL: gli strumenti di modifica lo rifiutano. Le correzioni che lo riguardano sono in formato-psb.md §9, non applicate al file. Va ripulito dai NUL (conservando la codifica) prima di poterlo correggere.

Come ripartire in cinque minuti

Dalla root del repo, con Python 3.12 (solo libreria standard):

python scripts/psb/prt.py 9253000117a.prt.35                 # indice delle sezioni
python scripts/psb/psb.py 9253000117a.prt.35 '*' out         # dump di ogni sezione in out/
python scripts/psb/psb.py 9253000117a.prt.35 LargeText - t   # traccia campo per campo (debug)
python scripts/psb/unz.py 9253000117a.prt.35 out             # decomprime le sezioni .Z
python scripts/psb/pbin.py out/SolidPrimdata.bin             # legge una sezione decompressa
python scripts/psb/batch.py "raw/*"                          # regressione sugli 89 file
python scripts/psb/norms.py 9253000117a.prt.35               # controllo norma 1 delle matrici
python scripts/psb/tagmap.py 9253000117a.prt.35 "raw/*"      # tag double -> prefisso, dalle norme
python scripts/psb/ctx.py raw/x.prt.1,VisibGeom,cf8          # hexdump attorno a un offset

Valori attesi oggi, da usare come regressione prima e dopo ogni modifica al parser:

Controllo	Atteso
psb.py 9253000117a.prt.35	29 sezioni OK, 5 no: AllFeatur (pop underflow sull'ultimo byte), MdlStatus e FeatDefs (pila non a zero), più l'intestazione delle due ultime
norms.py	good rows 5397 bad 0
batch.py "raw/*"	2152 sezioni lette, 74 no (misurato prima delle ultime correzioni ai tag: va rilanciato)

Se norms.py dà righe "bad" dopo una modifica, si è rotta la tabella dei double: è il controllo più sensibile che abbiamo.

Cosa è provato, e come

Cosa	Prova
Contenitore (offset = ultimo campo della prima riga, riga #Nome inclusa, indice a catena)	tutte le sezioni cominciano con e0 00 <radice>
Grammatica e tabella "dopo X viene Y"	lettura fino all'ultimo byte di tutte le sezioni; l'id nell'intestazione degli array coincide con quello calcolato
Tag dei double	norma 1 su 5397 righe; prefissi 3fd0-3fef e bfd0-bfef verificati uno a uno sugli 89 file
Costanti π, π/2, 2π, 3π/2 e negative	stesso rumore di mantissa nelle forme modificate (02 xx ...)
Sezioni .Z	la dimensione decompressa coincide con quella dichiarata nell'indice
Significato dei campi	nessuna: dedotto dai nomi

Cosa manca, in ordine di valore

1. Confronto con Creo. Aprire un file piccolo, annotare quote, parametri, massa, posizione di una faccia, e confrontare con il dump. Finché non c'è, tutto il doc è "livello 1 e 2".
2. Tabella dei float (tag 50-df). È una tabella di prefissi scelti per frequenza, non una formula. Il parser usa FBASE lineare, sbagliato per quei tag (lunghezza giusta, valore no). Senza, la mesh di SolidPrimdata (mv_p_NxNyNzxyz) non si esporta. Metodo che ha funzionato per le 29 voci note: normali unitarie, risolvere il modulo dalla norma. Va ripetuto su tutti i file di raw/ (ognuno ha SolidPrimdata), poi sostituire FBASE con un dizionario e far fallire il parser sui tag ignoti invece di inventare.
3. La pila dei contenitori. I valori sono giusti, l'annidamento no in alcuni punti:
   • LargeText di 24 file di raw/: alberi bilanciati (lesser_child, greater_child, balance_factor, backup_size). La regola post (puntatore "al successivo" scritto al livello del padre) copre un solo campo per struttura; qui i figli sono due.
   • srf_flip_dat (geometria), end2 (FeatDefs): "contenitore non in pila".
   • fine di AllFeatur/MdlStatus/FeatDefs: pila non a zero. Punto di partenza: default_close e locate in psb.py, con la traccia (- t).
4. Sezioni tipo b (IndentTag, FeatRefData) e tipo 11 Wildfire: illeggibili. Stessa lunghezza del chiaro, primi 4 byte in chiaro. Già escluso (vedi formato-prt-feature.md §1.3): XOR a chiave fissa, zlib, LZW. Non riprovare senza una coppia chiaro/cifrato dello stesso modello.
5. DispDataTable (tipo c): comincia con 1f 9d 10 ma l'LZW standard fallisce al secondo codice. Non indagato.
6. PSB_Tokens (ND:0:*): letti i quattro array, non il significato delle lettere di type_har. Ipotesi da cui partire: I consuma un intero, F un double, una lettera per le stringhe; M/O aprono oggetto e campo. Contare le occorrenze contro le lunghezze degli array la conferma o la smentisce in pochi minuti.
7. Costanti double ignote: 04 (vista come componente di tangente e come estremo di inviluppo), 0d (−0,5 da un solo caso), buco bffe contro bffd non deciso.
8. Portare il parser in C# accanto ad AsmRecordReader: solo dopo i punti 1 e 3.

Il ragionamento da adottare

È il metodo che ha portato fin qui. Va seguito anche per i punti aperti: ogni volta che è stato saltato, si è perso tempo.

1. Partire dal modello di chi scrive, non dai byte. Il file è l'uscita di un serializzatore generico che percorre strutture C. La domanda utile non è "cosa significano questi byte" ma "che regola semplice userebbe un programma per scriverli". Ogni marcatore ridondante (f7, f0-f4) esiste perché il lettore, da solo, avrebbe previsto un'altra cosa: capire la previsione spiega il marcatore.
2. Un'ipotesi alla volta, e un controllo che la possa smentire. Prima di scrivere codice dire cosa ci si aspetta di vedere se l'ipotesi è vera. Esempio: "se gli id sono progressivi, l'id nell'intestazione di unit_arr deve essere 0x14" (contato a mano: lo era).
3. Il parser è lo strumento di misura. Una regola è buona se fa arrivare la lettura all'ultimo byte di tutte le sezioni; l'errore dice dove guardare. Si corregge la regola generale, mai il caso singolo: un'eccezione scritta per una sezione ha sempre rotto un'altra.
4. Cercare i controesempi, non le conferme. Quando una regola spiega cinque casi, elencare per iscritto i casi noti (con i byte) e verificare che li spieghi tutti, compreso quello scomodo. La regola sulle chiusure implicite è nata mettendo in tabella dieci casi e cercando l'unica formulazione che non ne contraddiceva nessuno.
5. Ancorare i numeri a vincoli fisici, non all'aspetto. Un valore "plausibile" non è una prova. Lo sono: la norma 1 delle righe di una matrice di rotazione, valori noti (π, √2/2, 0,1, 25,4), la coerenza tra sezioni (lo stesso punto scritto due volte). Per i tag dei numeri: far risolvere il prefisso al vincolo (tagmap.py), non estrapolare una formula.
6. Separare ciò che è provato da ciò che è dedotto. Tokenizzazione (sequenza campo-valore), annidamento e significato dei campi sono tre cose con tre livelli di prova diversi. Nel doc ognuna va dichiarata col suo livello; "regge sui campioni" non è "è così".
7. Allargare il campione appena una regola regge. Un file solo nasconde le tabelle: i buchi nei prefissi negativi e la tabella dei float sono emersi solo confrontando più file. Dopo ogni modifica: norms.py sul campione, poi batch.py su raw/.
8. Quando due spiegazioni reggono entrambe, cercare il dato che le distingue invece di scegliere la più elegante (esempio: i tag 91-a0 sembravano negativi; li ha decisi una curva i cui parametri dovevano crescere da 3π/2).
9. Scrivere subito nel doc, con il sintomo e i byte. Una scoperta non scritta si rifà. Scrivere anche ciò che è stato escluso e perché.
10. Dire quello che non si sa. Una costante ignota resta "ignota" (<c04> nel dump), non riceve un valore inventato; un parser che non capisce si ferma, non restituisce un risultato parziale in silenzio.

Vicoli ciechi e trappole, per non rifarli

• Modello "pop = chiudi N livelli" puro: non basta. I marcatori f0-f4 compaiono solo quando la chiusura reale è diversa da quella che il lettore farebbe da solo; f0 vuol dire "resta qui". Ci sono volute quattro riscritture per arrivarci.
• Ordine dei campi per struttura (primo/successivo per schema): sbagliato. La tabella è piatta, per id, e vale l'ultima transizione vista.
• e4-e7 come "zeri": sono ripetizioni del valore precedente.
• Lo stesso id in contenitori diversi: succede con le varianti di unione (typed_data(...)); il parser le accetta e le conta in lenient.
• Tag double negativi lineari: no, ci sono tre buchi. Non fidarsi di un'estrapolazione fuori dagli intervalli verificati.
• Heredoc in Bash con \\0: lo strumento collassa le barre e scrive un NUL nel sorgente. Per creare file Python usare lo strumento di scrittura, non un heredoc.
• Git Bash e cd: gli script vanno lanciati dalla root del repo; dotnet run dentro PrepStep/ avvia la GUI.

Cronologia

Data	Fatto
2026-10-21	Albero delle feature, quote e geometria degli schizzi letti a pattern (formato-prt-feature.md, formato-prt-geometria.md)
2026-11-10	Contenitore corretto; grammatica PSB completa; tabella dei double; sezioni .Z; catalogo delle sezioni; parser di riferimento in scripts/psb/; formato-psb.md