[woahwhattheheck]

Closes #146

Summary

• add a typed, source-agnostic investor portfolio model and pure normalizer for heterogeneous asset/dashboard payloads
• recognize documented camelCase/snake_case identity, balance, metadata and support-status aliases without inventing missing asset facts
• recover later valid aliases when earlier aliases are nullish or malformed instead of letting one bad field mask a valid equivalent
• preserve unknown rows and mark unsupported/malformed rows with stable reason codes
• expose aggregate empty / ready / partial / unusable portfolio states plus exact base-unit display helpers
• export the normalizer/types from the SDK root and document supported aliases, assumptions, failure states and display behavior

Behavioral boundaries

• input order is preserved; normalization does not fetch, price, deduplicate or reorder holdings
• a generic assetId is not promoted to a contract ID; metadata.contractId is populated only from actual contractId / contract_id inputs
• decimal balances are derived only from integer base-unit values and explicit/default precision; malformed decimal balances are reported unsupported instead of guessed
• if a precision alias is present but none of the supplied aliases parses to a valid precision, normalization still fails closed with INVALID_DECIMALS rather than silently using the default
• normalization quality does not imply KYC, transfer eligibility, authorization, market value or legal ownership

Current carrier

• exact head: 38fa74799da9a6acc8d5d654369d726c95ac1dd9
• sponsor base: 69fff2c7e8c6fe801428fc1bb71d064c5c94949c
• 15 commits, 5 changed files, +578/-0

Focused evidence and limits

The focused fixture coverage exercises camel/snake contract-ID aliases, unknown-row preservation, unsupported/malformed states, exact signed balance formatting, all four aggregate portfolio states, source-order preservation and explicit default precision.

The current repair also pins heterogeneous alias recovery: an input with numeric assetId, decimal-string balance, invalid decimals, non-object metadata, then valid asset_id, raw_balance, asset_decimals and asset aliases normalizes to a supported C_RECOVERED holding with decimal balance 2.5. The normalizer remains parse-aware across alias families while retaining fail-closed precision semantics.

Provider readback verified the current normalizer/test blobs on this head. No broad test-suite, build, hosted-CI, dashboard integration, bounty-award or payout result is claimed by this metadata closeout.

Compensation request

Claimant and payee: @woahwhattheheck. This completed contribution is submitted through the issue's GrantFox Maybe Rewarded route. Please confirm the applicable bounty amount, assignment/award status, payout method, and timing.