handle nfo, reject cams ticob, flag dividend mismatches, name-match family pans

[sandeeprjs92]

Three registrar-file edge cases that came up in public feedback. Each commit addresses one concern, with tests. Research first, code second — see below.

Research summary

Before writing anything I searched public BSE StAR MF and CAMS docs and compared against the upstream source pipeline.

Code	Public docs	Source pipeline	Decision
NFO	Standard 'New Fund Offer' transaction type, documented by BSE StAR MF and every AMC.	Not handled.	Classify as (BUY, new_fund_offer).
TICOB / TOCOB	No public documentation found.	Upstream explicitly rejects these for CAMS with 'unsupported type'.	Port the rejection.
FC	Not found in BSE StAR MF, CAMS public docs, or upstream pipeline.	Not handled.	Intentionally left alone. Guessing at buy/sell semantics for a code I can't verify would be worse than a visible no-op. Commenters welcome to clarify their registrar's specific meaning and send a follow-up PR.
Dividend option mismatch	Real issue — SEBI renamed 'Dividend' to 'IDCW' in 2021, so historical feed files disagree with updated scheme masters.	Captures the raw flag but does not reconcile.	Capture it, normalise to canonical plan_type, reject the row to the correction queue on mismatch.
Messy investor data	—	Both pipelines match by PAN only.	Add canonical name fallback for family PANs.

Commits

1. add nfo classification and reject cams ticob/tocob

• CamsAdapter and all three KFintechFormatX adapters classify NFO as (BUY, 'new_fund_offer')
• New FeedAdapter.rejected_types class attribute (default empty set). CamsAdapter sets it to {'TICOB', 'TOCOB'}
• Cleaner.run drops rejected rows before any further processing
• Tests cover NFO classification for both registrars and TICOB/TOCOB rejection at the cleaner level

2. capture dividend option flag and reject plan_type mismatches

• CAMS adapter field map picks up REINVEST_F → dividend_option_flag, normalised via a {Y: idcw_reinvest, N: idcw_payout} lookup
• KFintech field map picks up DIVOPT → dividend_option_flag, normalised via a lookup that folds both legacy 'DIVIDEND PAYOUT' / 'DIVIDEND REINVESTMENT' wording and the current 'IDCW PAYOUT' / 'IDCW REINVESTMENT' wording to the same canonical values
• adapter.normalize() emits a plan_type_from_feed column after the rename
• core/validator.py raises ValidationError(CorrectionType.OTHER) when the feed's declared plan_type disagrees with the scheme master's value
• Silent feeds (empty DIVOPT / growth-only funds) don't trip the check — scheme master stays the source of truth
• Tests cover mismatch → raise, match → pass, silent feed → pass

3. resolve family pan by canonical investor name when ownership_type is silent

• New private _canonicalize_name helper — upper-case plus whitespace collapse, deliberately not fuzzy
• When a family PAN has multiple accounts and ownership_type doesn't tie-break, try a unique name-equality match before falling through to the individual default
• Only activates when (a) multiple accounts share the PAN, (b) the row has an investor_name, (c) exactly one stored account matches after canonicalisation. Ambiguous multi-match still raises AmbiguousPanError so operators resolve it in the correction queue
• The adapters already map CAMS INVNAME and KFintech INV_NAME to the investor_name canonical column, so no adapter change needed
• Tests cover happy match, multi-match falls through, silent feed unchanged

Local verification

• 105 unit tests pass (was 96 on main, added 9)
• Ruff clean
• Bandit clean
• Forbidden-strings scan clean (108 files)