Ontology — entities and the transaction taxonomy

The vocabulary. Every label the product uses for a thing or an event is defined here, with the code symbol that implements it. Status keys per README.md: ✅ grounded · ⚠️ VALIDATE · 🔲 TODO.

SME-reviewed 2026-06-18 (rounds 1–3). Thresholds, severities, and the taxonomy are signed off. The high-impact ontology items (non-income detection, credit-card treatment, loan stacking, paycheck-to-paycheck, new obligation/channel types) are implemented; a few refinements are queued — see validation-checklist.md → Round 3.

1. Entities and relationships

Borrower (a person/business being underwritten)
  └── Case (one underwriting pull for that borrower)
        └── Statement  ≈ one Account over one Period
              └── Transaction (one debit or credit, on a Date, with a running Balance)
                    └── Counterparty (the other side: payer or payee)

Invariant (the trust gate, ✅): a bank statement is self-verifying — for every row, previous_balance + credit − debit = balance. The whole chain plus the header endpoints must reconcile, or the data is not trusted (verify.py). This is the bedrock the rest stands on.

2. Transaction direction ✅

3. Channel / payment rail ✅ (NPCI / RBI rails)

How money moved. Grounded in India’s actual payment rails. Code: TxnMode, taxonomy.CHANNEL_PATTERNS.

FASTag is intentionally not a channel — useful for profiling, not underwriting (SME C1).

4. Income types ⚠️ VALIDATE (definitions standard; detection thresholds in metrics.md)

Credits that represent the borrower’s earning capacity, vs. non-income credits that must be excluded from income. Code: IncomeSource.kind, classified by taxonomy.classify_income_type (INCOME_TYPE_PATTERNS) over each detected recurring-income group; the salary hint (INCOME_HINT) plus the recurring-credit heuristic in analytics.py (thresholds in policy.py) decide what is income. Each source’s class is surfaced in the report. ✅ classes now distinguished.

Funds available, but NOT income ✅ (SME 2026-06-18) — taxonomy.NON_INCOME_PATTERNS

The cardinal underwriting error is counting capital movement as earning capacity. These credits are detected and excluded from income before any income test (classify_non_income_credit), even when recurring. Income increases earning capacity; these merely move, borrow, redeem, or return capital.

Core vs supplementary income ✅ (A1, SME 2026-06-18) — IncomeSource.tier

Affordability (FOIR, income band) is assessed on core income only; supplementary income supports the assessment but must not drive it — converting a one-off bonus into ongoing capacity is a classic error.

One-off bonuses/arrears aren’t annualised — a single non-recurring credit isn’t treated as monthly income at all. Business-income confidence (A4) is approximated by stability: unstable business income → supplementary.

5. Obligation types ⚠️ VALIDATE

Recurring debits that commit future income — the denominator’s numerator in FOIR (§ metrics.md). Code: Obligation.type, taxonomy.OBLIGATION_PATTERNS. Now modelled: the type is detected by the taxonomy; whether it loads FOIR is a policy.py toggle (counts_toward_foir), surfaced on each obligation as Obligation.counts_toward_foir and shown in the report (“not in FOIR” when excluded).

The “counts toward FOIR” column is the crux of underwriting correctness and is lender policy, not universal fact — so each ambiguous type is an explicit, overridable toggle (tenant.scoring_policy), never buried in a regex. Defaults above are ✅ SME-reviewed (2026-06-18).

Credit-card bill payments are NOT obligations (SME B3, taxonomy.CREDIT_CARD_PAYMENT): the payment amount is spend routing, not debt — counting it would double-count expenditure. Revolving behaviour (carried balance) is read instead from card finance/late charges → revolving_credit flag (§6). Detection method: an obligation is a recurring same-payee debit (≥ 2 months, median ≥ ₹1,000). Fixed vs variable (B1): amount CV ≤ obligation_fixed_max_cv (0.25) is fixed; a named credit obligation may vary up to obligation_variable_max_cv (0.60) and still count, flagged variable (floating EMI); a variable non-credit debit is lumpy spend, not an obligation. Amortisation (B2): non-monthly obligations (quarterly/annual) load FOIR at their monthly_equivalent (amount ÷ months-between-occurrences), so paying annually doesn’t look stronger.

6. Risk-signal types ✅ SME-reviewed 2026-06-18 (definitions grounded; severities in risk.md)

Events that indicate elevated credit risk. Code: RiskFlag.type; patterns in taxonomy.{BOUNCE,PENAL,CHEQUE_RETURN,CASH_DEPOSIT}. Severities are tuned to limit false positives: payment dishonours are recency-weighted (≤ 6 months full High, 7–12 partial Medium, older audit-only); negative-balance days are tiered (1–3 low / 4–10 medium / >10 high); cash-deposit intensity is borrower-segment dependent (salaried high > 25% of credits, self-employed medium

40%); circular transfers escalate to high when repeated across ≥ 3 months. Only repeated payment dishonours auto-decline (risk.md §2); other signals accumulate.

7. Where this lives in code today

The taxonomy has been lifted into server/src/domain/ (the plan this section used to track). The regex/threshold is the ontology entry now; what remains is genuine domain depth, not plumbing.

The high-impact ontology work is done. What remains is the SME’s lower-priority refinements (core/supplementary income A1, business-confidence A4, fixed/variable obligations B1, non-monthly amortisation B2, gambling/crypto D4, joint-account attribution E1 — see validation-checklist Round 3) and ongoing validation: promote ⚠️ defaults to ✅ grounded with a cited source in references.md. Lenders can already override any threshold in-app (Settings → Risk scoring policy) without waiting on that.