Punjab elector artifact¶

Punjab is Upnaam’s first complete person-level roll dataset. The Punjab adapter combines the restricted 2018 Punjab electoral-roll file from Dataverse dataset version 25.0 with the locally available Indicate transcription artifact. It emits one row for every one of the 19,119,006 source rows; it does not deduplicate the roll’s colliding or missing source identifiers.

Both person-level inputs and the result are restricted local artifacts. Upnaam commits the code and aggregate audit evidence, not names or other elector data.

Source and join contract¶

The roll input is punjab_all_clean+t13n.csv.gz from Dataverse dataset doi:10.7910/DVN/MUEGDT, version 25.0. The historical *_t13n columns in that file are not used: 12,003,070 of its elector_name_t13n values contain Malayalam characters and are not credible Punjabi-to-Latin transcriptions.

The replacement is Indicate’s local punjab_transliteration_subset.parquet, which has 19,119,006 rows. The adapter joins the files by zero-based source-row order only after verifying exact equality of all 11 repeated native fields in each batch:

elector and father-or-husband names;
assembly and parliamentary constituency names;
main town, police station, mandal, revenue division, and district; and
polling-station name and address.

Any row-count or native-field disagreement fails the stage. Row order is a validated source contract here, not a general-purpose linkage method.

The source id is not an elector key: 99,261 non-unique ID values occur in 2,130,443 rows, and 654,308 rows have a missing or blank ID. The adapter therefore defines elector_id as muegdt-v25-punjab:<source_row> and retains the source value separately as source_elector_id.

Resolution assumptions¶

The stage applies only the approved resolver-v1 Punjab rule:

Preserve the native and Latin full names exactly.
Tokenize the native name under normalization-v1.
Ignore only the versioned leading honorifics already declared by Upnaam.
Require at least two alphabetic characters in an eligible token.
Abstain when fewer than two eligible native tokens remain.
Otherwise select the final eligible native token. Do not exclude Kaur, Singh, Kumar, Devi, or any other token by spelling.
Copy the Latin token at the same position only when the complete native and Latin token sequences have equal length.
If token counts differ, retain the resolved native surname, leave the Latin and ASCII surname fields null, and report token-count-mismatch. Do not use fuzzy matching or a nearby token.
Convert an aligned Latin token to a lowercase ASCII comparison form with Unicode compatibility decomposition and combining-mark removal. For example, Rāj becomes raj. This is not cross-spelling canonicalization: Kanr remains kanr unless a later reconciliation stage supplies independent evidence for one unambiguous anchor.

This stage does not use the relative name, house number, sex, English name parsers, Levenshtein distance, household propagation, land records, ration cards, or a learned name model to change the selection.

Output contract¶

The main fields are:

Field	Meaning
`source_row`	Zero-based row in the frozen Dataverse file
`elector_id`	Unique source-revision-qualified artifact key
`source_elector_id`	Original, non-unique and nullable roll ID
`name_native_raw`	Exact Gurmukhi elector name
`name_latin_raw`	Exact Indicate full-name transcription
`surname_raw`	Exact selected Gurmukhi token
`surname_source_normalized`	Conservatively normalized Gurmukhi token
`surname_latin_raw`	Exact aligned Indicate token, including diacritics
`surname_latin_normalized`	Lowercase ASCII comparison form, when alignment succeeds
`surname_canonical`	Current canonical form; initially identical to the Latin-normalized form
`canonicalization_status`	`identity_unmapped`, `normalization_unavailable`, or `not_applicable` after surname abstention
`canonicalization_reason`	Initially `no_reconciliation_decision`, `normalization_unavailable`, or `surname_not_selected`
`canonicalization_provenance`	Null until an anchored decision is applied
`canonicalization_revision`	Canonicalization contract revision
`surname_position`	`last` for a resolved native surname
`surname_provenance`	`written_final_token` for a resolved native surname
`abstained`	Whether native recorded-surname selection abstained
`abstention_reason`	`missing-name`, `no-eligible-token`, or `single-token-name`
`transliteration_status`	`aligned`, `token-count-mismatch`, `ineligible-latin-token`, or `no-surname-selected`

Because native resolution and transliteration are separate decisions, abstained = false can coexist with a null surname_canonical: in that case surname_raw remains populated and transliteration_status explains why no Latin comparison value was asserted.

surname_latin_normalized makes exact grouping and downstream joins convenient but does not claim that OCR or spelling variants have been merged. For example, the source native token ਕੰਰ is transcribed as Kanr and remains kanr; Upnaam does not silently rewrite it to kaur in this adapter.

The artifact also retains the source row’s number, year, filename, part, house number, age, sex, relationship, relative name, and selected native/Latin geography fields. Every row carries the normalization, resolver, and transliteration revision. The stage manifest records SHA-256 fingerprints for both inputs and all outputs.

Run the adapter with:

upnaam resolve-punjab ROLL.csv.gz INDICATE.parquet OUTPUT.parquet \
  --audit AUDIT.json --summary SUMMARY.csv

All paths are explicit. No cloud query is made.

First complete run¶

The frozen v1 run produced:

Result	Rows	Share of all rows
Source and output	19,119,006	100.00%
Native surname resolved	16,899,471	88.39%
ASCII comparison form resolved	16,898,030	88.38%
Abstained	2,219,535	11.61%
Resolved native surname with token-count mismatch	1,319	0.0069%
Resolved native surname with ineligible Latin token	122	0.0006%

Native-surname coverage is 85.75% for female rows and 90.66% for male rows. The difference is descriptive of this final-token rule and source data; it is not a validated sex-specific accuracy estimate. The checked-in punjab_elector_resolution.csv contains the complete aggregate coverage table by sex and relationship field.

The ten most frequent ASCII comparison forms illustrate both the scale and the need to keep variant resolution separate:

Form	Rows
`singh`	6,434,719
`kaur`	4,289,329
`kanr`	1,190,956
`kumar`	1,060,342
`rani`	595,446
`devi`	564,068
`laal`	219,871
`ram`	199,539
`sharma`	175,583
`kumaari`	137,682

Of the kanr rows, 1,190,954 come directly from native ਕੰਰ transcribed as Kanr; only two come from ਕੰੜ. The adapter correctly preserves that observation instead of declaring it equivalent to kaur. Establishing such equivalence is the job of the later evidence-backed variant stage.