cadrumo.core.field_role module¶

The closed vocabulary a tabular column’s meaning is mapped onto.

A CSV or spreadsheet arrives with header names the product does not control: a real libro registro carries every field the invoice importer needs under Spanish names it has never seen, plus a retención column it has no slot for at all. The mapping step answers “what does this column MEAN”, once per file, against this closed set — never per row, and never over a cell value.

That closedness is the anti-fabrication control. Role assignment is an allow-list selection over these members, so the only thing the mapping step can emit is a member; deterministic code then copies each cell under the chosen mapping. A column whose meaning cannot be established maps to FieldRole.UNMAPPED and is reported, so a file is never refused whole for carrying a column the product does not know, and an unknown column is never quietly copied into a field it does not belong to.

Member values are byte-identical to the column tokens the tabular importers already accept, so a role resolves against an existing importer column without a second translation table in between. The set is deliberately WIDER than those importers: retención and the suplido/recargo/total terms of the arithmetic closure, and the bank-movement booked date and amount, are roles the product must be able to recognise in a source table even where no importer column exists for them yet.

The set spans two source shapes that are NOT the same document. Most members describe an invoice book; FieldRole.BOOKED_DATE and FieldRole.MOVEMENT_AMOUNT describe a bank statement, which has no issue date, no base and no total. They are declared separately rather than borrowed from the nearest invoice member because a role is a claim about MEANING, and a near-fit reused across shapes propagates the wrong claim downstream to every consumer that trusts the name.

The axis lives in core because its producers, the deterministic copy step and the operator-facing report of unmapped columns sit in different packages, and core is the only home all of them reach without depending on each other.