feat(ein): emit additive ein_prefixed + EIN2 columns (ADR 0036)

[Thiyaghessan]

Sitrep — ADR 0036

• Implements: ADR 0036 (E1, CORE scope) — additive, coercion-safe EIN renderings on the CORE tiers.
• Diverged from ADR: none.
• Needs ADR review: none. (One parity observation flagged below for the N1 backlog — not a contract-shape decision, not blocking.)
• Contract surfaces touched (for the contracts reconcile):
  • conventions/ein-format.md — the ein_prefixed rendering (ein-XX-XXXXXXX), shared with the BMF order; whichever lands first carries it.
  • The CORE tier contract YAML(s) in nccs-contracts/contracts/ (core-990, core-legacy, core-panel) — gain ein_prefixed + EIN2 columns.
  • Not edited here — these are the reconcile work-list for a nccs-contracts session.

What this does

Emits two purely additive columns on every CORE tier output (processed/core, processed_legacy/core, processed_merged/core), alongside the unchanged canonical dashed ein:

column	value	role
ein_prefixed	ein-XX-XXXXXXX	new lowercase, coercion-safe house key (leading alpha forces text typing)
EIN2	EIN-XX-XXXXXXX	legacy-compatibility alias (exact legacy name + format)

Both are bijective with ein and NA-preserving. The canonical ein is externally load-bearing (five external surfaces per ADR 0036) and is left untouched — this is additive, not a reformat.

Implementation

• R/transforms/ein.R — ein_to_prefixed() / ein_to_ein2() (twins of nccs-data-bmf/R/ein.R, byte-identical casing + prefixing) + add_ein_renderings().
• R/03_harmonize.R / R/03_legacy_harmonize.R — add the columns last in apply_transforms, after the blanket financial coercion, so the character columns are never coerced numeric. Covers 990, 990ez, 990pf (SOI) and 990combined, 990pf (legacy).
• R/04_derive_combined.R — added to COMBINED_UNIVERSAL_COLS so they survive project_to_shared into the SOI 990combined.
• Merged tier (R/04_legacy_merge.R) — propagate automatically as shared columns; both sides derive them from the merge key ein, so they are always identical → no false disagreement-audit rows. (No code change needed.)
• R/06_dictionary.R — disambiguating UNIVERSAL_DICTIONARY_ROWS entries stating which EIN to join on (forward → ein/ein_prefixed; legacy merge → EIN2).
• R/quality/post_checks.R — whitelist both from check_schema extras so they aren't flagged as unexpected columns.
• Tests — unit coverage for the renderings (incl. NA preservation, casing) and project_to_shared propagation.

N1 parity note (backlog, not for this PR)

The two renderings are kept in exact parity with the BMF order. The upstream canonical ein formatter (transform_ein) has already drifted between the repos and I did not reconcile it (per the brief — consolidation is the N1 backlog item, not a unilateral call):

• empty string → NA here vs "00-0000000" in BMF;
• CORE rejects >9-digit input (→ NA); BMF keeps it (warns).

This affects only edge-case handling of malformed/empty EINs in the base ein, not the format/casing of the new columns.

Tests

Rscript tests/run_all.R → 257 passed, 2 failed. The 2 failures (expected_col_count for 990pf 2022 / 990 2024) are pre-existing — they fail identically on a clean checkout of main (IRS var-matrix counts, unrelated to this change).

🤖 Generated with Claude Code