prep-step/docs/formato-asm-record.md

Decodifica strutturale del .asm Creo: record, membri, family table

Questo documento descrive il formato record per record del .asm Creo, ricavato per reverse engineering su un campione di assiemi reali e verificato confrontando l'output con le BOM esportate da Creo per gli stessi file. Sostituisce, per l'estrazione dei componenti, l'euristica testuale ("codice che compare almeno due volte") descritta in formato-asm.md: quella era una statistica sui nomi, questa legge la struttura effettiva dei record.

Implementazione: lettura in PrepStep/AsmRecordReader.cs (condivisa con la GUI, Form1.EstraiCodiciReferenziati in fase "Trova componenti referenziati"/"Verifica completezza" - con fallback su AssemblyComponentScanner per i file che non rispettano il formato validato), resa in formato BOM e ricorsione sui sottoassiemi in scripts/CreoBom.cs (via #:project).

Stato della validazione. Due livelli di prova, da non confondere:

1. Byte-per-byte contro BOM Creo di riferimento (la prova forte): 3 assiemi del reverse engineering iniziale, più 5 casi reali aggiunti in seguito, ciascuno con la sua BOM esportata da Creo messa a confronto riga per riga con l'output di CreoBom.cs — 9284218024b.asm (albero profondo, multi-livello), 2546220101.asm/2546220101_c04.asm.1 (istanza di family table isolata), 2546220101.asm risalvato con un componente soppresso, 9244218080_c01.asm (sottoassieme montato due volte), 9284208092_D110.asm (revisione del figlio). Ognuno di questi è citato per nome nella sezione del documento a cui si riferisce, così resta verificabile quale affermazione poggia su quale file.
2. Su tutti i 350 .asm reali di raw/, solo conteggi interni e coerenza con l'euristica testuale (AssemblyComponentScanner), non contro BOM di riferimento: usato per calibrare le soglie dei controlli di sicurezza (§7) su scala, non per dimostrare la correttezza dei valori estratti file per file.

Un'affermazione verificata solo al livello 2 (conteggi su scala) è più debole di una verificata al livello 1 (BOM reale) - il testo lo distingue sempre esplicitamente.

---

1. Intestazione

Il file si apre con un header ASCII a righe terminate da \ + newline:

#UGC:2 ASSEMBLY 2038 1760 805 1 1 15 4000 2022414 000002d0 \
#- VERS 0 0                                               \
#- HOST                                                   \
#- LINK                                                   \
#- DBID                                                   \
#- REVS 0,                                                \

ASSEMBLY distingue il tipo di modello. Gli altri campi numerici non sono stati decodificati e non servono per la BOM. Dopo l'header inizia il corpo binario. Il corpo non è compresso: i nomi dei modelli sono in chiaro, 1 byte per carattere (Latin1 — Encoding.Latin1.GetString, stesso metodo già usato in AssemblyComponentScanner.cs per leggere il file come testo senza alterarne i byte).

2. Il formato dei record

Il corpo è una serializzazione a marcatori. I byte \xe0-\xff sono marcatori di struttura, tutti gli altri sono dati. I marcatori osservati:

byte	significato dedotto
\xe0	inizio campo: \xe0 <tipo> <nome campo>\0 <valore>
\xe1	valore nullo / vuoto
\xe2	inizio struttura o unione (per i parametri: il byte dopo è il discriminante)
\xe3	inizio struttura, usato per gli elementi di un array
\xf1	apre un contenitore (visto prima di un array)
\xf7	id di schema: \xf7 <n> identifica il layout dei record che seguono
\xf8	array: \xf8 <conteggio> ... <elementi>
\xfb	lo schema è definito in linea nel primo elemento dell'array
\xf4	chiude una sezione (seguito da #\n#<NomeSezione>\n)

Il byte <tipo> dopo \xe0 codifica il tipo del valore. Osservati: \x00 struttura/nullable, \x01 intero, \x02 array numerico, \x0a stringa terminata da \0.

2.1 Interi

Gli interi sono big-endian con la lunghezza codificata nei bit alti del primo byte, per non collidere con i marcatori \xe0+:

primo byte	byte totali	valore
0x00-0x7f	1	il byte stesso
0x80-0xbf	2	(b0 & 0x3f) << 8 | b1
0xc0-0xdf	3	(b0 & 0x1f) << 16 | b1 << 8 | b2

Esempi verificati: \x2e = 46; \x80\x81 = 129; \xc0\x4d\x51 = 19793. Questa regola è stata ricavata dalla necessità di far quadrare il conteggio dei membri: con la lettura a 1 byte fisso i campioni grandi si disallineavano. Non è confermata da una specifica; regge sui campioni disponibili al momento del reverse engineering.

In CreoBom.cs è AsmRecordReader.AsInt, applicata al testo decodificato Latin1 (ogni char della stringa corrisponde 1:1 a un byte, quindi indicizzare la stringa o l'array di byte originale dà lo stesso offset).

2.2 Compressione per schema

Un array \xf8 <n> \xf7 <idSchema> \xfb scrive il primo elemento con tutti i nomi di campo per esteso; gli elementi successivi sono posizionali, senza nomi. È il motivo per cui nel file si vedono i nomi dei componenti "nudi", uno dopo l'altro, senza etichetta. Per leggere l'elemento N bisogna conoscere lo schema definito dall'elemento 1.

---

3. L'elenco dei componenti: la chiave members

La chiave members è l'elenco dei componenti diretti dell'assieme (livello 1), nell'ordine di montaggio.

\xe0 \x00 "members" \0
  \xf1 \xf8 <N> \xf7 <idSchema> \xfb
    \xe3 \xe0\x01 "id"\0 <int>
         \xe0\x01 "type"\0 <int>
         \xe0\x0a "name"\0 <stringa>\0
         \xe0\x0a "family_name"\0 <stringa>\0
         \xe0\x00 "tha_ref"\0 \xe1
         \xe0\x02 "e1"\0 ...  "e2" ... "e3" ... "origin" ...
    \xe3 <id> <type> <name>\0 <family_name>\0 <resto posizionale>
    \xe3 <id> <type> <name>\0 <family_name>\0 <resto posizionale>
    ...

Campi utili:

• id — identificatore del componente dentro questo assieme. È lo stesso numero che Creo mostra come "Componente ID N". Serve da chiave per collegare il membro ad altre sezioni (vedi family table, §4).
• type — 1 = sottoassieme (.asm), 2 = parte (.prt). Sui campioni osservati compaiono solo questi due valori.
• name — il file su disco, senza estensione. Per le family table è il generico (UNI6592), non l'istanza.
• family_name — sui campioni disponibili è sempre uguale a name. Non porta quindi l'informazione sull'istanza; il nome è fuorviante.
• e1, e2, e3, origin — la matrice di posizionamento (assi + origine). Non decodificati: non servono per la BOM, ma occupano il resto del record e hanno lunghezza variabile.

N (il conteggio dichiarato) è il numero totale di occorrenze, non di codici distinti: una parte montata 4 volte conta 4 e compare in 4 record con id diversi. Il conteggio va usato come controllo di correttezza: se i record trovati non sono esattamente N, la lettura si è disallineata e va segnalata un'eccezione invece di restituire un risultato parziale silenzioso — vedi AsmRecordReader.LeggiMembri, che lancia InvalidDataException in questo caso.

La sezione termina a \xf4\x04#\n#MdlStatus\n.

3.1 Come lo legge AsmRecordReader.LeggiMembri

Il parser non ricostruisce lo schema completo (servirebbe decodificare le matrici). Si ancora invece al pattern \xe3 <int> <int> <stringa>\0 <stringa>\0 (AsmRecordReader.MemberRegex, una regex .NET sul testo Latin1 del file) e salta il resto del record fino al \xe3 successivo che soddisfa il pattern. La doppia stringa terminata da \0 rende i falsi positivi improbabili, e il conteggio dichiarato N fa da rete di sicurezza.

ponytail: scansione a pattern invece del parser di schema — il punto debole è che si appoggia al conteggio per accorgersi di un errore. Da sostituire con la lettura dello schema se dovessero comparire campioni che non quadrano.

---

4. Family table: dove sta il nome dell'istanza

Le parti normalizzate (viti, rondelle, spine, boccole) sono istanze di family table. In Creo esiste un solo file, il generico (UNI6592.prt), che contiene una tabella di varianti; ogni variante è un'istanza (R8--_-_U6592_AISI304). La BOM elenca le istanze, il disco contiene il generico. La sezione members cita solo il generico: senza risolvere ConfigName (sotto), il livello 1 produrrebbe UNI6592 dove la BOM dice R8--_-_U6592_AISI304.

Il collegamento sta in un record di parametro applicato al membro:

\xe3 "ConfigName"\0 \xe2 \x33 [\xf7 <idSchema>] <nome istanza>\0 <id membro> \x82\x7b \xe1\xe1

• \xe2\x33 — parametro di tipo stringa (\x33 = '3'). Confronto: \xe2\x32 è un parametro numerico, es. DENSITA.
• <nome istanza> — il nome esatto che la BOM stampa.
• <id membro> — l'id del record members a cui il parametro si applica, con la codifica intera di §2.1. È questo il collegamento.
• \xf7 <idSchema> compare solo sulla prima occorrenza (schema definito in linea), poi è omesso.
• \x82\x7b — costante (= 635) identica su tutte le occorrenze di tutti i campioni. Significato ignoto, presumibilmente attributi/flag del parametro. AsmRecordReader.ConfigNameRegex la usa come ancora di fine record; se un campione futuro avesse un valore diverso, il match salterebbe silenziosamente (nessun contatore di sicurezza analogo a quello di members copre questo caso).

ConfigName compare esattamente per i membri che sono istanze, e per nessun altro. L'algoritmo è quindi: leggere members, costruire la mappa id membro → nome istanza dai record ConfigName (AsmRecordReader.LeggiMembri, dizionario istanze), e sostituire il nome dove la mappa ha una voce. Il generico resta disponibile come Membro.Generico.

Avvertenza. ConfigName sta in mezzo a parametri palesemente aziendali (TIPO_PARTE, CLASSE_RICAR, GR_PRODOTTO, TECN_RIORDINO), quindi potrebbe non essere un meccanismo standard di Creo ma una convenzione interna. Regge sui campioni disponibili, ma su file provenienti da un'altra installazione va riverificato prima di fidarsene.

4.0.1 Eccezione: componenti da pattern/array feature (#AF<n>)

Un componente creato da un pattern/array feature (stessa geometria ripetuta N volte da una feature di pattern, non N placement manuali distinti) ha un ConfigName con un nome nella forma <codice>#AF<n> (n = indice dell'istanza nel pattern), es. 9244250136_C01#AF0. Non è un'istanza di family table: è un tag interno di disambiguazione fra le ripetizioni del pattern. La BOM reale di Creo lo ignora e mostra il codice pulito, unendo le occorrenze duplicate in una sola riga con la quantità totale.

Osservato su 9244250136.asm: 4 dei suoi 8 membri hanno ConfigName con suffisso #AF, due dei quali (_C03#AF0 e _C03#AF1) sono lo stesso codice con n diverso — la BOM li mostra come un'unica riga 9244250136_C03 con quantità 2. Senza normalizzare il suffisso, ogni istanza del pattern risulterebbe un componente distinto (e con nome sbagliato). AsmRecordReader rimuove #AF\d+$ da ogni valore di ConfigName prima di usarlo (SuffissoArrayFeatureRegex). Scoperto durante un test end-to-end su un albero reale più ampio degli 8 campioni originali (9284218024b.asm, confrontato con la sua BOM Creo di riferimento) — non era presente in nessuno degli 8 campioni usati per il reverse engineering iniziale.

4.0.2 Istanza risolta direttamente in members, senza passare da ConfigName

Non tutti i membri che sono istanze di family table hanno un record ConfigName associato. Per alcune parti commerciali/normalizzate non-UNI, il campo name (e allo stesso modo family_name) del record members (§3) porta già per intero la notazione <nome istanza><generico> invece del solo nome generico:

\xe3 <id> <type> "<istanza><generico>"\0 "<istanza><generico>"\0

È la stessa notazione istanza→generico della §4.1 sotto, ma qui compare dentro il record members stesso, come valore diretto del componente - non nell'elenco di riferimenti geometrici di cui parla la §4.1 (quello sì da ignorare per la BOM). Il generico fra < e > è il file realmente indicizzato sul disco; il nome prima di < è quello che la BOM mostrerebbe.

AsmRecordReader.LeggiMembri lo riconosce per i membri senza un ConfigName corrispondente il cui campo name rispetta per intero il pattern <testo><testo>: il testo dopo l'ultima < (fino alla > finale) diventa il generico da cercare nell'indice, quello prima diventa il nome mostrato. Senza questo split, il codice cercato nell'indice sarebbe la stringa intera con le parentesi comprese, mai presente nell'indice - il componente risulterebbe erroneamente "non trovato".

4.1 Una seconda pista, che NON va usata per la BOM

Altrove nel file compaiono stringhe nella forma istanza<generico>:

\xe2\x02 "R8--_-_U6592_AISI304<UNI6592>"\0

Documenta la stessa relazione istanza→generico in modo autonomo ed è utile come riscontro incrociato (è lo stesso pattern <codice><GENERICO> già sfruttato dall'euristica testuale in formato-asm.md per le family table non-UNI). Non è però una lista dei componenti: su un campione produceva 26 voci contro 17 membri reali, includeva alcuni nipoti (figli dei sottoassiemi) ma non tutti, e ripeteva le stesse voci più volte. È la lista dei riferimenti geometrici dei vincoli di accoppiamento, non una distinta. Usarla per la BOM dà risultati sbagliati sia in eccesso sia in difetto.

---

5. Il nome proprio del modello

La BOM intesta i blocchi col nome del modello, non del file: il file 9244248550b.asm.11 produce Assieme 9244248550B contiene:. Il nome sta nel primo record objname del file:

\x00 "objname"\0 \xe2 \xe0\x01 "object_type"\0 <int> \xe0\x0a "name"\0 <nome>\0

La prima occorrenza è il modello stesso; quelle successive sono altri oggetti referenziati (disegni, modelli citati). AsmRecordReader.NomeProprio cerca solo la prima occorrenza (Regex.Match, non Matches), verificato su tutti i campioni disponibili durante il reverse engineering.

---

6. Generare la BOM: ricorsione e formato di output

members dà un solo livello. La BOM di Creo è ricorsiva: apre anche i .asm dei sottoassiemi. Implementato in CreoAsm.GeneraBom/Render in scripts/CreoBom.cs.

6.1 Struttura del file BOM

• Codifica UTF-8 con BOM (EF BB BF), fine riga CRLF.
• Due righe vuote in testa, poi il primo blocco.
• Tre righe vuote fra un blocco e il successivo, due prima del riepilogo. Il file termina con un solo CRLF.
• Riga voce: {qta:6} {tipo:>12} {nome} — cioè quantità allineata a destra su 6 caratteri, spazio, tipo allineato a destra su 12, due spazi, nome.
• Intestazioni: Assieme <nome> contiene: per la radice, Sottoassieme <nome> contiene: per gli altri.

6.2 Ordine dei blocchi

Visita depth-first pre-order: si emette il blocco di un sottoassieme e subito dopo, ricorsivamente, quelli dei suoi sottoassiemi, prima di passare al fratello successivo. Ogni modello compare una volta sola anche se montato più volte (deduplica per nome, CreoAsm.Blocchi).

Verificato. 9244218080_C01.asm monta 2605410010_C01 due volte (scripts/9244218080_c01.asm.1 + scripts/9244218080_c01.bom.2 di riferimento): la BOM Creo mostra un solo blocco Sottoassieme 2605410010_C01 contiene: con quantità 2 in testa, non due blocchi separati, e CreoBom.cs riproduce l'output esatto senza modifiche. Confermata anche la moltiplicazione delle quantità nel riepilogo (§6.3): le parti di 2605410010_C01 compaiono raddoppiate (1→2, 1→2, 16→32).

6.3 Riepilogo finale

Summary of items for <radice>: elenca solo le parti, con la quantità totale moltiplicata lungo l'albero (una parte in 4 esemplari dentro un sottoassieme montato 2 volte conta 8), nell'ordine di prima comparsa nella visita depth-first (CreoAsm.Sommario). Una parte che compare a più livelli occupa la posizione della sua prima comparsa e somma le quantità.

6.4 Risoluzione dei file dei sottoassiemi

È il punto che il formato non risolve: il .asm registra il nome del modello, non il percorso. Servono quindi cartelle di ricerca fornite dall'esterno (-p/--path). CreoAsm.CreaFinder indicizza <nome>.asm.<rev> senza distinzione di maiuscole e, a parità di nome, prende la revisione più alta presente.

Verificato: è la scelta giusta. Il .asm padre non registra la revisione attesa del figlio (cercata e non trovata, vedi §7), ma non serve: confermato che Creo stesso apre sempre la revisione più alta disponibile di un componente, indipendentemente da quale fosse presente quando l'assieme padre fu salvato l'ultima volta. Caso reale controllato: 9284208092_D110.asm (salvato 2018-08-01) referenzia 9284202481.prt, che sulla share ha revisioni sia del 2014 (v1-v3, presenti all'epoca) sia del 2024 (v4-v6, arrivate anni dopo) - Creo carica v6, non v3. CreaFinder che prende sempre la revisione più alta in cartella replica esattamente questo comportamento, non è un'assunzione azzardata. Vedi formato- asm.md §"Risoluzione ricorsiva dell'albero" per le trappole storiche su questo punto (con l'euristica testuale - restano valide, sono su un problema diverso: trovare la cartella giusta, non quale revisione preferire).

Se un sottoassieme non si trova, il blocco viene emesso con *** NON RISOLTO: file .asm non trovato *** e le sue parti restano fuori dal riepilogo. Il risultato è dichiaratamente incompleto invece che silenziosamente sbagliato.

---

7. Stato di ogni punto aperto

Tabella di riferimento: cosa è provato, come, e cosa resta genuinamente ignoto. Il dettaglio di ciascun punto segue sotto, in due gruppi.

Punto	Stato	Prova
Deduplica blocchi + moltiplicazione quantità (§6.2/§6.3)	Risolto	BOM reale (§7.1)
Revisione del figlio che il padre si aspetta (§6.4)	Risolto	BOM reale (§7.1)
Stato soppresso/escluso in members	Risolto	BOM reale (§7.1)
Family table di assiemi (rilevamento)	Risolto: serve la conferma del nome proprio (objname), il solo model_name dava falsi positivi	BOM reali + albero raw/ completo (§7.1)
Family table di assiemi (contenuto di ogni istanza)	Non risolto, nessun impatto sulla BOM (fallback già corretto)	Scan sull'intera share (§7.2)
Costante \x82\x7b in ConfigName	Significato ignoto, rischio coperto	Scala 350 file (§7.2)
Occorrenze multiple di members (simplified rep)	Mai osservato, rischio coperto	Scala 350 file (§7.2)
Matrice di posizionamento (e1/e2/e3/origin)	Non letto, nessun impatto sulla BOM	— (§7.2)
Campi numerici dell'header dopo ASSEMBLY	Non letto, nessun impatto sulla BOM	— (§7.2)
Divergenza family_name ≠ name	Mai osservata, non letta	— (§7.2)

"Rischio coperto" vuol dire: il codice non sa cosa significhi il byte, ma verifica un invariante che lo renderebbe visibile (eccezione) se mai smettesse di valere - non è una prova che il byte non conti mai, è la garanzia che se contasse il programma lo segnalerebbe invece di sbagliare in silenzio.

7.1 Risolti con una BOM Creo di riferimento

• Deduplica blocchi e moltiplicazione quantità. 9244218080_C01.asm monta 2605410010_C01 due volte (scripts/9244218080_c01.asm.1 + scripts/9244218080_c01.bom.2): la BOM Creo mostra un solo blocco Sottoassieme 2605410010_C01 contiene: con quantità 2 in testa (non due blocchi separati), e le sue parti compaiono raddoppiate nel riepilogo (1→2, 1→2, 16→32). CreoBom.cs riproduce l'output esatto senza modifiche: la deduplica per nome (CreoAsm.Blocchi) e la moltiplicazione lungo l'albero (CreoAsm.Sommario) sono il comportamento reale di Creo, non solo un'assunzione.

• Revisione del figlio. 9284208092_D110.asm (salvato 2018-08-01) referenzia 9284202481.prt, che sulla share ha revisioni sia del 2014 (v1-v3, presenti quando il padre fu salvato) sia del 2024 (v4-v6, arrivate anni dopo). Confermato direttamente in Creo: apre v6, non v3 - sempre la revisione più alta disponibile, indipendentemente da quale fosse presente all'ultimo salvataggio del padre. CreoAsm.CreaFinder, che prende sempre la revisione più alta trovata in cartella, replica esattamente questo comportamento.

• Stato soppresso/escluso. Stesso assieme 2546220101.asm risalvato da Creo con 2546220101_C02 soppresso (scripts/2546220101.asm.1 + scripts/2546220101.bom.1, con le parti/sottoassiemi correlati). Un componente soppresso non produce alcun record in members: sparisce e basta, il conteggio dichiarato scende di conseguenza (\xf8 03 invece di \xf8 04). Nessun marcatore di stato da gestire: CreoBom.cs sul file risalvato riproduce esattamente la BOM di riferimento senza modifiche al parser.

  Sparisce da members, non dal file. La feature che lo posiziona resta, e con essa la stringa Componente ID <n> (<codice>.PRT) (localizzata come in AssemblyComponentScanner.HaPlacement). Per la BOM va ignorata - Creo non elenca i soppressi - ma il file di quel componente serve comunque per aprire l'assieme: se manca, Creo fallisce il caricamento con "dati di input non completi" ([-4], cioè PRO_TK_E_NOT_FOUND). Verificato su un caso reale: un assieme che non si apriva dalla cartella raw/, e che si è aperto senza errori copiandoci dentro quel solo file. AsmRecordReader.EstraiCodiciSoppressi li restituisce a parte, apposta per questo - vedi §7.3.

• Family table di assiemi — rilevamento. Non solo le parti normalizzate (§4) possono essere family table: un intero assieme può esserlo. Osservato su 2546220101.asm (dentro l'albero di 9284218024b.asm): il file generico ha una propria sezione members che elenca il contenuto di UNA rappresentazione (3 cuscinetti + 1 sotto-assieme, dati arbitrari), ma la BOM Creo per lo stesso file mostra 4 istanze diverse (2546220101_C01.."_C04", tre "Parte" e una "Sottoassieme" - tipi diversi fra loro), ciascuna con un contenuto diverso. Il nome istanza qui non passa da ConfigName (verificato: nessuna occorrenza letterale nel file), ma da una coppia di record distinta subito dopo l'header del modello:

  \xe0\x01model_t_type\0<int>\xe0\x0amodel_name\0<codice>_C0n\0\xe0\x0ageneric_name\0\0
      ...stamp\0\xe2\xf2\xf7<idSchema>
      (\xe3<type>\x02<codice>_C0n\0\0\xe2)*   -- un'occorrenza per ogni istanza sorella
  \xf4
  

  Quando questo succede il file generico è già di per sé un'istanza (model_name porta il suffisso _C0n, non è neutro) e stamp elenca le sorelle.

  Il record model_name da solo non è un'identità. Su file reali quel record nomina quasi sempre un altro modello - tipicamente uno dei membri del file stesso, a volte un codice imparentato - e in quei casi members è già corretto e va usato. Serve una conferma indipendente: il nome proprio del modello (objname, §5). LeggiMembri segnala la family table solo se objname esiste e coincide con model_name privato del suffisso _C0n; negli altri casi legge members normalmente.

  Il controllo più largo (senza la conferma di objname) era la causa di falsi "componenti mancanti": il parser esatto rifiutava file perfettamente leggibili, si ripiegava sull'euristica testuale e quella estraeva codici che non esistono, riportati poi come componenti non trovati nell'indice. Verificato contro BOM Creo di riferimento: sui file dove il segnale scattava senza conferma di objname, members elenca esattamente i componenti della BOM reale (anche nello stesso ordine); uno di questi file è stato inoltre aperto in Creo, e l'albero del modello mostra gli stessi componenti, senza alcuna family table. Con la conferma di objname richiesta, tutti i .asm di una cartella raw/ reale (351 file, alberi completi di più macchine) si leggono col parser esatto, zero ricadute sull'euristica.

  Da tenere presente: il sintomo dipende da come il file è stato salvato, non solo dal modello. Rileggendo una revisione più recente dello stesso assieme generico, il record di identità può non esserci più e members elencare direttamente tutte le istanze, col tipo giusto per ciascuna - cioè esattamente quello che mostra la BOM. Il blocco quindi non è una proprietà stabile del codice: va valutato file per file, revisione per revisione.

  Verificato anche che il fallback su AssemblyComponentScanner risolve già correttamente il caso vero: i nomi delle istanze compaiono come testo puro nel campo stamp, e l'euristica ("codice che compare almeno due volte") li trova senza bisogno di decodificare stamp. E che una singola istanza, se esportata da Creo come file a sé (Family Table → istanza → "Salva una copia"), è un .asm/.prt normale senza traccia di family table al suo interno - letto correttamente dal parser esatto (2546220101_c04.asm.1, verificato contro 2546220101.bom.1).

7.2 Non risolti

• Family table di assiemi — contenuto di ogni istanza. Come recuperare il contenuto specifico di un'istanza senza che esista già un file separato per essa sul disco (il caso comune, se nessuno l'ha mai esportata a parte con "Salva una copia"): il meccanismo dietro stamp non è stato decodificato oltre a nome+tipo di ciascuna istanza sorella: stamp porta solo i nomi delle sorelle, non il loro contenuto, quindi non è la struttura da cui partire per risolvere questo punto.

  Resta aperto solo per completezza: sui file dove il segnale scatta davvero (con conferma del nome proprio, §7.1) il parser si ferma invece di restituire un contenuto sbagliato, e il chiamante ripiega sull'euristica testuale, che i nomi delle istanze li trova comunque come testo puro. Nessun comportamento dell'app dipende da questa decodifica.

• Costante \x82\x7b nei record ConfigName: significato ignoto. Rischio coperto - LeggiMembri conta le occorrenze grezze di ConfigName e le confronta col numero di match del regex; se un campione avesse un valore diverso, il regex non farebbe più match (prima: in silenzio) e ora lancia eccezione invece di restituire il nome generico al posto dell'istanza senza dirlo. Verificato su tutti i 350 .asm di raw/: 215 usano davvero ConfigName, 0 mismatch.

• Occorrenze multiple di members (rappresentazioni semplificate, mai osservate). Rischio coperto - LeggiMembri lancia eccezione se ne trova più di una invece di prendere silenziosamente la prima senza sapere se sia quella giusta. Verificato su tutti i 350 .asm di raw/: sempre esattamente una occorrenza.

• La matrice di posizionamento (e1, e2, e3, origin): formato numerico non decodificato, nessun impatto sulla BOM (non letta da nessuna parte del codice).

• I campi numerici dell'header dopo ASSEMBLY: non letti, nessun impatto sulla BOM.

• family_name: sempre uguale a name su tutti i campioni disponibili; non si sa in quale situazione divergerebbe, né se il codice dovrebbe fare qualcosa se succedesse (oggi non la usa in nessun modo, legge solo name).

7.3 Due domande diverse: cosa va in distinta, cosa serve per aprire

È la lezione che costa di più riscoprire, quindi sta qui in chiaro: la lista dei componenti della BOM e la lista dei file che servono a Creo per aprire l'assieme non coincidono. La seconda è più lunga.

Lista	Serve per	Si ottiene con
Componenti della distinta	BOM, verifica completezza	LeggiMembri / EstraiCodiciReferenziati (sezione members)
File necessari al caricamento	popolare raw/ per l'export STEP	i precedenti più EstraiCodiciSoppressi e EstraiCodiciRiferimentiEsterni (§7.5)

La differenza sono i componenti soppressi (§7.1) e i riferimenti esterni (§7.5): fuori dalla BOM, ma senza il loro file Creo non apre l'assieme. Chi popola raw/ deve quindi usare l'unione; chi genera la BOM o verifica la completezza deve usare solo i membri, altrimenti quelle voci diventano falsi "componenti mancanti".

Il sintomo, se si sbaglia, non assomiglia per niente alla causa: Creo Distributed Batch fallisce con Carica modello in Creo Pro | Non riuscito | [-4] Errore: Dati di input non completi - un messaggio che non nomina il file mancante. Il modo più rapido per trovarlo è aprire l'assieme in Creo dalla cartella raw/ (non dalla share, dove i file ci sono tutti e quindi si apre senza errori) e cercare nell'albero la voce con l'icona rossa.

7.4 Lo stesso codice esiste in più cartelle della share

Sulla share 13% dei codici (5.193 su 39.274 fra prt e asm) ha la versione più alta in più cartelle, con contenuto diverso. Non sono revisioni: sono copie parallele, lasciate da studi preliminari, allestimenti fiera, cartelle di lavoro datate, raccolte temporanee.

Il .asm non dice quale copia usa: verificato che non registra né il percorso, né l'UOBJ_ID del figlio (che pure distingue le copie), né la revisione attesa. Cita solo il nome del modello. Quale copia venga caricata lo decide Creo al momento dell'apertura, e la regola pratica è: prima la cartella del modello che la referenzia.

Non esiste quindi un criterio globale corretto - e i numeri lo confermano: nel 79% dei conflitti nessuna delle copie sta in una cartella "ufficiale" (…\M_B, …\A), perché il conflitto è fra due istantanee parallele, ognuna autoconsistente con i propri componenti. Per data, per versione e per posizione sono equivalenti: solo il contesto di chi referenzia discrimina.

Conseguenze per il codice:

• Form1.ScegliPerCartella risolve ogni componente preferendo la copia nella stessa cartella dell'assieme che lo referenzia, e solo in mancanza ripiega su versione più alta e data più recente. Form1.CartellaDiOrigine ricostruisce quella cartella per gli assiemi di partenza, che arrivano dalla fase precedente senza portarsela dietro.
• La vista files_ultima_versione (vedi db-cad-index.md) rompe il pareggio fra copie di pari versione in modo deterministico invece che arbitrario.
• Resta un rischio noto: quando il componente non sta nella cartella del suo assieme, la scelta torna a essere una scommessa. Se un assieme non si apre da raw/, è la prima cosa da verificare - 9244206098 è il caso reale che ha portato a questa sezione: due copie di pari versione, una del 2011 in una cartella di file sciolti e una del 2026 accanto all'assieme, e in raw/ finiva quella del 2011.

7.5 Riferimenti esterni: la tabella dei modelli citati

Terzo modo in cui un .asm dipende da un file che non è fra i suoi membri, dopo i soppressi (§7.1) e le copie ambigue (§7.4). Un assieme che porta assembly feature o datum copiati da un altro modello lo cita in una tabella a parte, che non è members e non lascia una stringa Componente ID …: i due lettori esistenti non la vedevano.

Struttura: un array aperto da \xf2\xf7\x05 e chiuso da \xf3, con elementi \xe3\xe2<tipo><nome>\x00. Il nome può portare il suffisso #AF<n> di §4.0.1 e/o la notazione istanza<generico> di §4.0.2 - il file su disco è il generico:

f2 f7 05 e3 e2 01 "9255708017#AF2<9255708017>" 00 ...  ->  9255708017
         e3 e2 02 "9255700181" 00 ...                  ->  9255700181
f3

Va letta con EstraiCodiciRiferimentiEsterni, e - a differenza dei soppressi - si ricorre dentro: Creo carica il modello citato con tutti i suoi componenti, che quindi servono anch'essi in raw/. La tabella contiene anche nomi di feature (MIRROR3, CHAMFER1, M10_TAPPED_HOLE1), indistinguibili dai modelli guardando il record: non è un problema perché chi la usa cerca ogni nome nell'indice e ignora quelli che non ci sono - per lo stesso motivo questi codici non devono finire fra i "non trovati".

Il caso reale: 9255728001 falliva in Distributed Batch con lo stesso [-4] Dati di input non completi di §7.3 perché il suo sottoassieme 9255728001_200 referenzia per assembly feature 9255708017 e 9255708018 (e con loro 9255700181/182/183), e monta una vite V6-12--_-_U5933_C<UNI5933> il cui generico uni5933.prt non era in raw/. Nessuno dei sei file compariva in members né fra i piazzamenti.

8. Uso

dotnet run scripts/CreoBom.cs -- raw/9244228558.asm.20 -p M:\modelli -o out\9244228558.bom.1
dotnet run scripts/CreoBom.cs -- raw/9244228558.asm.20 -p M:\modelli    # stampa a video
dotnet run scripts/Analyze.cs -- raw/9244228558.asm.20 "ConfigName"    # dump dei byte per investigare a mano

Senza -p/--path, la ricerca dei sottoassiemi usa la cartella del file di partenza. -p è ripetibile per più cartelle. -o scrive il file col BOM UTF-8 e CRLF descritti al §6.1; senza -o il testo va su stdout (con \n al posto di \r\n, per leggibilità in console).