Data Dictionary + Rules Matrix Entity Schemas • Field Specifications • Constraint Logic • Optimization Rules • Ranking Rules BIX Technology Corp | Purlend / PreFi, Inc. | CONFIDENTIAL | Engineering Spec v1.0
This document is the BIX engineering specification for the Clarity Engine’s data model. It defines every entity, every field (required and optional), all derived calculations, the constraint detection rules, the optimization move schema, the scenario output schema, the ranking rules, and the explanation object model. Engineers should use this alongside the Architecture Blueprint and Master PRD.
The Clarity Engine is built around 15 canonical entities. Every component in the system reads from or writes to objects based on these entities.
# Entity Layer Purpose 1 Borrower Intake / Normalization Core borrower identity, flags, and goal weights 2 CoBorrower Intake / Normalization Secondary borrower with independent income and liabilities 3 IncomeSource Intake / Normalization Individual income stream with type, amount, and qualifying treatment 4 Liability Intake / Normalization Individual debt obligation with optimization eligibility flags 5 Asset Intake / Normalization Individual asset with liquidity and eligibility classifications 6 Property Intake / Normalization Subject property with geographic enrichment and eligibility flags 7 Deal Financial Twin The canonical deal state: borrower + property + intent + derived metrics 8 Program Program Library Loan product rules, eligibility thresholds, and pricing parameters 9 Incentive Incentive Intelligence DPA, grant, CRA, and employer assistance programs with eligibility logic 10 Constraint Constraint Detection Detected blocker with type, severity, gap value, and routing 11 OptimizationMove Move Library Transformation strategy with impact estimates, conditions, and compliance notes 12 Scenario Scenario Engine A specific deal structure with full financial outcomes and move tags 13 Recommendation Recommendation Engine Safe / Optimal / Transformational scenario selection with key moves 14 Explanation Explanation Layer Plain-language borrower communication fields for Nova and advisors 15 AuditEvent Governance Immutable log entry for every system action across all components
Required (yes) = engine cannot process without this field. Shown with green background in tables. Optional (no) = used when available; engine degrades gracefully without it. Shown with gray background. Type codes: string, decimal, integer, boolean, date, datetime, enum, array, text Enum values are defined in the Program Library API. All enums must be versioned.
The root entity for every deal. Contains identity, flags, and the borrower’s objective weight vector — the goal priorities that control scenario ranking.
Field Name Type Req Example Notes / Rules borrower_id string yes
Unique identifier. UUID recommended. first_name string yes David
last_name string yes Kawata
date_of_birth date no 1978-01-10 Required for age-sensitive programs (e.g. reverse mortgage eligibility). ssn_hash string yes [hashed] Store hashed only. Never plaintext. citizenship_status enum no
marital_status enum no
household_size integer no 3 Required for USDA and some DPA income limit calculations. first_time_homebuyer_flag boolean yes true Controls DPA, grant, and CRA eligibility. veteran_flag boolean yes false Triggers VA eligibility check and benefit activation flow. disability_flag boolean no false VA funding fee waiver; accessibility program eligibility. self_employed_flag boolean yes true Triggers Schedule C / bank statement income treatment path. primary_residence_intent boolean yes true Required for occupancy classification. target_monthly_payment decimal no 3200.00 Borrower-stated comfort threshold. Used in ranking engine. target_cash_to_close decimal no 15000.00 Borrower-stated threshold. Used in constraint detection. goal_priority_payment integer yes 5 1-5 scale. Feeds scenario ranking weight vector. goal_priority_cash integer yes 4 1-5 scale. goal_priority_purchase_power integer yes 5 1-5 scale. goal_priority_speed integer yes 3 1-5 scale. goal_priority_wealth integer yes 4 1-5 scale. Drives long-term interest savings weight.
Derived Borrower Metrics Derived Field Type Formula / Logic monthly_gross_income decimal SUM(IncomeSource.qualifying_monthly_amount) for this borrower total_monthly_liabilities decimal SUM(Liability.monthly_payment WHERE include_in_dti_flag = true) liquid_assets_total decimal SUM(Asset.balance WHERE liquid_flag = true AND eligible_for_closing_flag = true) reserves_months decimal liquid_assets_total ÷ projected_monthly_housing_payment borrower_profile_type enum Logic: if self_employed_flag → self_employed; if retirement income dominant → retired; else salaried or variable approval_readiness_score decimal Internal weighted heuristic. Inputs: credit score band, DTI margin, reserves, documentation completeness.
One record per income stream per borrower. A borrower may have multiple IncomeSource records.
Field Name Type Req Example Notes / Rules income_id string yes
Unique per income stream. borrower_id string yes
FK to Borrower. income_type enum yes
Values: base_salary, bonus, commission, overtime, self_employment, rental, social_security, pension, disability, alimony, boarder, other gross_monthly_amount decimal yes 12500.00 Before underwriting treatment. qualifying_monthly_amount decimal yes 10416.67 After program-specific treatment (averaging, add-backs, gross-up). Engine-calculated. income_frequency enum yes
Values: monthly, biweekly, weekly, annual history_months integer no 24 Required for bonus, overtime, commission, self-employment qualifying. continuance_likely_flag boolean no true Required for VOE-dependent income types. documentation_status enum no
Values: stated, partial, verified add_back_amount decimal no 28700.00 Sum of Schedule C add-backs. Applies to self_employment type. gross_up_applied_flag boolean no false True if non-taxable income grossed up by 25% (SS, disability). averaging_method enum no
Values: current_only, two_yr_avg, lower_of_two_years
BASE_SALARY: Use current annual salary ÷ 12. Verify with paystub + W-2. BONUS / OVERTIME / COMMISSION: Require 2-year history. Use 24-month average. If declining year-over-year, use lower year. SELF_EMPLOYMENT: Run full Schedule C add-back algorithm. Use 24-month average of net + add-backs. If declining > 10% YoY, use lower year or deny income. RENTAL: Apply 75% vacancy factor to gross rent from Schedule E or executed lease. Require appraisal market rent analysis if no existing lease. SOCIAL_SECURITY / DISABILITY (non-taxable): Gross up by 25% per Fannie Mae and FHA guidelines. Example: $2,400/mo SS → $3,000 qualifying. BOARDER INCOME: FHA allows up to $200/mo for 9-12 months documented history. Not allowed in conventional.
One record per debt obligation. Engine evaluates each for DTI inclusion, optimization eligibility, and payoff strategy.
Field Name Type Req Example Notes / Rules liability_id string yes
Unique per debt. borrower_id string yes
FK to Borrower. liability_type enum yes
Values: credit_card, auto, student_loan, personal_loan, mortgage, installment, heloc, child_support, alimony, business_debt creditor_name string no Chase
balance decimal yes 3200.00
monthly_payment decimal yes 95.00 Use minimum payment for revolving. Use actual for installment. interest_rate decimal no 24.99 APR. Used in optimization ranking (consolidation candidates). credit_limit decimal no 10000.00 Required for utilization calculation. utilization_pct decimal no 0.32 Derived: balance ÷ credit_limit. Key for credit score optimization. months_remaining integer no 18 For installment exclusion logic (<10 payments remaining). secured_flag boolean yes false
eligible_for_payoff_flag boolean yes true Engine can propose payoff as optimization move. include_in_dti_flag boolean yes true False if: <10 payments, co-signed with 12mo third-party history, business debt documented on biz return. cosigned_flag boolean no false Triggers third-party payment history check. business_debt_flag boolean no false If true, verify business pays via CPA letter. May exclude from DTI.
Derived Liability Metrics Derived Field Type Formula / Logic total_revolving_balance decimal SUM(balance WHERE liability_type IN [credit_card, heloc]) total_revolving_utilization decimal SUM(balance WHERE revolving) ÷ SUM(credit_limit WHERE revolving) total_monthly_dti_obligations decimal SUM(monthly_payment WHERE include_in_dti_flag = true) high_interest_debt_total decimal SUM(balance WHERE interest_rate ≥ 15%) optimization_opportunity_score decimal Weighted rank: balance, interest_rate, utilization impact, DTI impact per dollar of payoff months_to_exclusion_eligibility integer MAX(0, months_remaining - 10). Months until debt can be excluded from DTI.
Field Name Type Req Example Notes / Rules asset_id string yes
Unique per asset account. borrower_id string yes
FK to Borrower. asset_type enum yes
Values: checking, savings, brokerage, retirement_401k, retirement_ira, crypto, gift, real_estate_equity, business, other balance decimal yes 42000.00 Current account balance. vested_pct decimal no 1.00 For retirement accounts. Fannie Mae: 60% of vested balance counts. liquid_flag boolean yes true False for illiquid assets (real estate equity, unvested retirement). eligible_for_closing_flag boolean yes true False for assets that cannot be sourced (cash gifts without documentation, recent large deposits). eligible_for_reserves_flag boolean yes true Reserves can be met with retirement accounts even if not used for closing. haircut_pct decimal no 0.40 Retirement: 0.40 (use 60% of balance). Crypto: 1.00 (must liquidate). Default: 0.00. source_verified_flag boolean no true 60-day statement history required. seasoning_days integer no 65 Days funds have been in account. Crypto requires 60-day post-liquidation seasoning. gift_letter_received_flag boolean no false Required for gift funds.
Derived Asset Metrics Derived Field Type Formula / Logic net_eligible_assets decimal SUM(balance * (1 - haircut_pct)) WHERE eligible_for_closing_flag = true retirement_reserve_credit decimal SUM(balance * 0.60) WHERE asset_type IN [retirement_401k, retirement_ira] funds_available_for_closing decimal SUM of eligible, sourced, non-reserved liquid assets allocated to closing funds_available_for_reserves decimal net_eligible_assets - funds_allocated_to_closing + retirement_reserve_credit total_asset_strength_score decimal Internal heuristic: liquidity + reserve depth + documentation completeness
Field Name Type Req Example Notes / Rules property_id string yes
Unique identifier. address string yes
city string yes Irvine
state string yes CA Two-letter USPS code. zip_code string yes 92618
county string no Orange Derive from zip if not provided. census_tract string no 06059032045 11-digit FIPS tract code. Required for CRA and DPA geo-matching. purchase_price decimal no 650000.00 Required for purchase deals. estimated_value decimal no 650000.00 AVM estimate or appraisal. Required for refi deals. property_type enum yes SFR Values: sfr, condo, townhome, 2_unit, 3_unit, 4_unit, pud, manufactured occupancy_type enum yes
Values: primary, second_home, investment unit_count integer yes 1 1-4 for residential programs. hoa_monthly decimal no 210.00 Required if HOA present. Included in PITIA. annual_property_tax decimal no 7800.00 Annual amount. Divide by 12 for monthly escrow. annual_insurance decimal no 1800.00 Hazard insurance. Add flood if required. flood_zone_flag boolean no false Triggers flood insurance requirement. avm_confidence_score decimal no 0.87 From Attom / Clear Capital. Low confidence → flag for appraisal. appraisal_status enum no
Values: estimated, ordered, completed, waived condo_project_status enum no
Values: not_applicable, approved, pending_review, non_warrantable
Derived Property Metrics Derived Field Type Formula / Logic monthly_tax decimal annual_property_tax ÷ 12 monthly_insurance decimal (annual_insurance + annual_flood_insurance) ÷ 12 conforming_limit decimal Lookup by county from FHFA conforming limit table. Updated annually. loan_limit_bucket enum If loan ≤ conforming_limit: conforming. If ≤ high_balance_limit: high_balance. Else: jumbo geographic_incentive_flag boolean True if census_tract OR county matches any record in Incentive database property_eligibility_flags array List of flags: condo_review_needed, flood_insurance_required, manufactured_restricted, investment_limited estimated_pitia decimal Estimated P+I (at scenario rate) + monthly_tax + monthly_insurance + hoa_monthly + estimated_MI. Calculated per scenario.
The Deal object is the canonical deal state. It is the primary object passed between all components in the Decision Core.
Field Name Type Req Example Notes / Rules deal_id string yes
Unique per deal session. deal_type enum yes
Values: purchase, rate_refi, cash_out_refi, debt_consolidation_refi, term_refi borrower_id string yes
FK to Borrower. coborrower_id string no
FK to CoBorrower if applicable. property_id string yes
FK to Property. intent_type enum yes
Values: purchase, refinance, equity_access, uncertainty requested_loan_amount decimal no 617500.00 Borrower-specified. If null, engine calculates max. down_payment_amount decimal no 32500.00 Purchase deals. estimated_closing_costs decimal no 12500.00 From fee worksheet or lender estimate. seller_concession_amount decimal no 7500.00 Purchase deals. Reduces cash to close. desired_cash_out_amount decimal no 40000.00 Refi cash-out deals. current_mortgage_balance decimal no 410000.00 Refi deals. current_rate decimal no 7.25 Refi deals. Basis for savings calculation. current_payment_pi decimal no 2528.00 Current P+I. Used in payment delta calculation. remaining_term_months integer no 320 Refi deals. deal_state enum yes
Values: active, approved_now, approved_with_action, path_in_progress, closed, archived created_at datetime yes
last_updated_at datetime yes
Updated on every state change.
Derived Deal Metrics Derived Field Type Formula / Logic ltv decimal requested_loan_amount ÷ MIN(purchase_price, estimated_value) cltv decimal (first_lien + all_subordinate_liens) ÷ estimated_value housing_ratio decimal projected_pitia ÷ monthly_gross_income (front-end DTI) dti_ratio decimal (projected_pitia + total_monthly_dti_obligations) ÷ monthly_gross_income (back-end DTI) cash_to_close decimal down_payment + closing_costs - seller_concession - incentive_credits - lender_credits payment_delta decimal projected_new_pitia - current_payment_pi (refi deals) recapture_months integer estimated_closing_costs ÷ monthly_savings_from_refi payment_capacity_margin decimal target_monthly_payment - projected_pitia (positive = room remaining)
Field Name Type Req Example Notes / Rules program_id string yes
Unique per program version. program_name string yes Conv 30yr Fixed
program_family enum yes
Values: conventional, fha, va, usda, cra, portfolio, non_qm, jumbo term_options_months array yes [360,180] Allowed term lengths in months. min_credit_score integer no 620 Fannie: 620. FHA: 580. VA/USDA: lender overlay (typically 620-640). max_ltv decimal no 0.97 Program maximum. LTV check applied per scenario. max_dti_manual decimal no 0.45 Manual underwrite maximum. max_dti_automated decimal no 0.50 AUS (DU/LP) maximum. Conventional Fannie: up to 50% with DU approval. min_down_payment_pct decimal no 0.03 3% Conventional, 3.5% FHA, 0% VA/USDA. reserve_requirement_months integer no 2 Minimum post-closing reserves in months of PITIA. mi_required_flag boolean yes true True if PMI/MIP required based on LTV. mi_annual_rate decimal no 0.0065 Annual MI rate as % of loan. Used in PITIA calculation. fha_upfront_mip_pct decimal no 0.0175 FHA UFMIP: 1.75% of loan, financed or paid at closing. primary_only_flag boolean yes false Some programs require primary occupancy only. allows_dpa_flag boolean yes true DPA combinability. allows_gift_funds_flag boolean yes true Gift fund eligibility. allows_boarder_income_flag boolean yes false FHA allows boarder income. Conventional does not. property_types_allowed array yes ["sfr","condo"] Controls property eligibility check. occupancy_types_allowed array yes ["primary"]
version string yes
Guidelines version. Must be updated when guidelines change. effective_date date yes 2025-12-01 Date this version becomes effective.
The Incentive Intelligence Service maintains this database. Programs are geo-indexed and match borrower + property eligibility criteria.
Field Name Type Req Example Notes / Rules incentive_id string yes
Unique per program. incentive_name string yes CA Dream For All
incentive_type enum yes DPA Values: dpa, grant, cra_credit, employer_assistance, lender_credit, fhfa_spc geography_scope string yes CA State / county / census_tract code. Supports geo-lookup. max_benefit_amount decimal no 15000.00 Maximum dollar benefit. May vary by deal. benefit_pct_of_price decimal no 0.03 If benefit is % of purchase price. Use with max_benefit_amount cap. income_limit_pct_amfi decimal no 1.20 As % of Area Median Family Income. Engine calculates borrower eligibility. first_time_buyer_required boolean yes true Controls eligibility filter. primary_residence_required boolean yes true
combinable_with_programs array no ["FHA","Conv"] Programs this incentive stacks with. stacking_conflicts array no [] Incentive IDs that cannot be combined. repayment_type enum yes
Values: forgivable, repayable, deferred, outright_grant forgiveness_years integer no 5 Years of occupancy required for forgiveness. funding_status enum yes
Values: active, limited, suspended, exhausted funding_source string no
last_verified_date date yes 2026-03-01 Database freshness signal.
Field Name Type Req Example Notes / Rules constraint_id string yes
deal_id string yes
FK to Deal. constraint_type enum yes
Values: dti, cash_to_close, credit, payment, program, property, timing, confidence severity enum yes
Values: low, medium, high, blocking primary_flag boolean yes true Only one primary constraint per deal session. current_value decimal no 22000.00 The borrower’s current value on the constrained metric. threshold_value decimal no 15000.00 The target or program limit for that metric. gap_value decimal no 7000.00 gap = current_value - threshold_value. Positive = over limit. explanation_code string yes
Internal code for Explanation Layer lookup. routing_path string yes
Optimization path to activate. Maps to decision tree branches A-H.
The move library is a versioned catalog of transformation strategies. Each move is a discrete, testable function.
Field Name Type Req Example Notes / Rules move_id string yes
Unique move identifier. move_name string yes Pay Revolving to 30% Utilization
move_category enum yes
Values: debt, credit, income, asset, program, structure, incentive, seller applicable_constraint_types array yes ["dti","credit","payment"] Which constraints trigger this move. required_conditions array yes ["revolving_balance_present","liquid_assets_available"] All conditions must be true for move to apply. expected_impact_types array yes ["lower_dti","increase_score"] Dimensions this move affects. impact_fico_pts_low integer no 20 Low-end FICO improvement estimate. impact_fico_pts_high integer no 40 High-end FICO improvement estimate. impact_dti_delta decimal no -0.03 Expected DTI reduction. Negative = reduction. complexity enum yes LOW Values: low, medium, high timeline_days_low integer no 0 Fastest execution in days. timeline_days_high integer no 45 Slowest expected execution. borrower_action_required boolean yes true False for moves the engine applies internally (program switch). borrower_cost_type enum no
Values: cash, time, none compliance_notes text no Verify sourced funds per URLA gift documentation requirements.
enabled_flag boolean yes true False to temporarily disable a move without deleting. version string yes v1.0 Move library version. All moves must be versioned.
A Scenario is a specific combination of program + moves + incentives applied to a borrower’s DealState, with all financial outcomes calculated.
Field Name Type Req Example Notes / Rules scenario_id string yes
Unique per scenario. deal_id string yes
FK to Deal. scenario_label string yes
Human-readable label for display. scenario_type enum yes
Values: baseline, safe, optimal, transformational, fallback base_program_id string yes
FK to Program. applied_move_ids array yes
Ordered list of moves applied. incentive_ids array no
Incentives included in this scenario. projected_rate decimal yes 6.125 Note rate as decimal percentage. projected_loan_amount decimal yes 620000.00
projected_purchase_price decimal no 650000.00 Purchase deals. projected_down_payment decimal no 30000.00
projected_pitia decimal yes 3198.00 Full payment including taxes, insurance, HOA, MI. projected_cash_to_close decimal yes 14250.00 After all credits and incentives applied. projected_dti decimal yes 0.462 Back-end DTI. projected_ltv decimal yes 0.954
projected_fico_post_moves integer no 662 Estimated score after moves applied. approval_confidence decimal yes 0.84 0.0-1.0 scale. Combines: program eligibility, DTI margin, LTV, score. total_interest_estimate decimal no 518442.00 Full-term interest cost. monthly_savings_vs_current decimal no 182.00 Refi deals: delta from current payment. execution_complexity enum yes
Values: none, low, medium, high action_plan_steps array no [] For transformational scenarios: ordered action steps. valid_flag boolean yes true False if scenario violates any program rule. Must be filtered out before ranking. delta_vs_baseline object yes
{} JSON: purchase_price_delta, payment_delta, cash_delta, interest_delta. compliance_status enum yes
Values: passed, flagged, failed. All flagged scenarios require human review.
Field Name Type Req Example Notes / Rules recommendation_id string yes
deal_id string yes
FK to Deal. safe_scenario_id string yes
Highest confidence scenario. optimal_scenario_id string yes
Best weighted outcome. transformational_scenario_id string no
Null if no materially better path exists. current_affordability_estimate decimal no 485000.00 What borrower qualifies for today (baseline max purchase price). optimized_affordability_estimate decimal no 565000.00 After top optimization moves applied. key_moves array yes ["apply_dpa","payoff_cc_2800"] The 1-3 moves that create the biggest improvement. recommended_next_step string yes Apply for local DPA program and pay $2,800 on Chase Visa Plain language next action. confidence_summary enum yes
Values: high, medium, low. Summary across top scenarios. human_review_required_flag boolean yes true True during MVP phase. False once confidence thresholds are established. created_at datetime yes
Nova and the Advisor Dashboard consume Explanation objects. Every field must be present for the engine to be considered production-ready for borrower-facing output.
Field Name Type Req Example Notes / Rules explanation_id string yes
recommendation_id string yes
FK to Recommendation. borrower_status_text text yes You appear positioned around $485,000 today based on your current income, debts, and credit profile. Plain language. Nova-ready. primary_blocker_text text yes The main limitation right now is your available cash to close.
improvement_unlock_text text yes Two adjustments could move your range significantly higher.
key_moves_text text yes 1. Apply for a local assistance program that may cover $9,500. 2. Pay down about $2,800 across two credit cards.
tradeoff_text text yes This option reduces your cash needed upfront but does not change your monthly payment.
action_plan_text text yes Here is your 45-day path to improved approval range... Step-by-step next actions. scenario_comparison_text text no Your safe option gets you to $485K. Your optimized option gets you to $565K. For multi-scenario comparison. disclosure_text text yes All estimates are subject to income verification, credit review, and property appraisal. Required disclosure. confidence_text text no Based on the information provided, this scenario shows strong qualification indicators.
Every action in every component generates an AuditEvent. This log is immutable. It is the foundation for fair lending review, regulatory examination, and system debugging.
Field Name Type Req Example Notes / Rules audit_event_id string yes
UUID. Immutable. deal_id string yes
FK to Deal. event_type enum yes
Values: intake_received, profile_normalized, baseline_run, constraint_detected, moves_evaluated, scenario_generated, scenario_ranked, recommendation_created, explanation_generated, nova_output_sent, human_override, deal_state_changed source_component string yes ScenarioEngine Component name string. timestamp datetime yes
inputs_hash string yes [hash] Hash of input payload for tamper-evidence. outputs_hash string yes [hash] Hash of output payload. rules_version_tag string yes rules_v1.0.3 Rules version active at time of event. actor_type enum yes
Values: system, human_advisor, human_admin actor_id string no
Required when actor_type is human. override_rationale text no Advisor confirmed income manually. Required for human override events.
The rules matrix defines the decisioning logic for each component in the engine. Rules are versioned and must be updated when program guidelines change.
7A. Baseline Eligibility Rules Rule ID Rule Name Input Fields Logic Output
Min Credit Score Check credit_score, program.min_credit_score IF score < min_score THEN fail ineligible + reason
Max DTI Check dti_ratio, program.max_dti_automated IF dti > max_dti_automated THEN conditional; IF > max+5% THEN fail conditional or ineligible
Max LTV Check ltv, program.max_ltv IF ltv > max_ltv THEN fail ineligible + reason
Occupancy Check occupancy_type, program.occupancy_types_allowed IF occupancy NOT IN allowed list THEN fail ineligible
Property Type Check property_type, program.property_types_allowed IF type NOT IN allowed list THEN fail ineligible
Reserve Check reserves_months, program.reserve_requirement_months IF reserves < requirement THEN conditional conditional
Loan Limit Check loan_amount, property.conforming_limit IF loan > conforming THEN flag jumbo. IF loan > jumbo limit THEN fail conventional flag or fail
VA Eligibility Check veteran_flag, dd214_verified, service_months IF veteran AND service_months ≥24 AND honorable discharge THEN eligible for VA VA eligible flag
Self-Employed History self_employed_flag, income history_months IF self_employed AND history < 24 months THEN conditional conditional + documentation flag
Condo Warrantability property_type, condo_project_status IF condo AND status = non_warrantable THEN FHA/portfolio only program restriction flag
7B. Constraint Detection Rules Rule ID Rule Name Trigger Condition Constraint Output Severity Logic
DTI Blocker dti_ratio > program.max_dti_automated type: dti | gap: dti - max High if > max+3%; Medium if > max; Low if within 2%
Cash-to-Close Shortfall cash_to_close > funds_available_for_closing type: cash_to_close | gap: delta High if gap > 20% of needed; Medium if 10-20%; Low if <10%
Payment Discomfort projected_pitia > target_monthly_payment type: payment | gap: delta High if > target+15%; Medium if > target+5%
Credit Below Threshold credit_score < program.min_credit_score OR score in poor pricing tier type: credit | gap: points needed Blocking if below all programs; High if below conventional
Program Mismatch all eligible programs ineligible for current profile type: program | reasons: list High if only non-QM options remain
Property Issue condo_project_status = non_warrantable OR property_type restricted type: property | flags: list High if limits to 1 program
Timing / Action Gap all constraints resolvable with defined actions, no immediate path type: timing | action_plan: [] Medium (always has a path)
Confidence Gap borrower shows uncertainty indicators or incomplete profile type: confidence Low (education mode trigger)
7C. Optimization Selection Rules Rule ID Rule Name If Constraint Activate Move Categories (in order) Expected Outcome
DTI Path dti 1. debt_payoff 2. debt_exclusion 3. income_add 4. co_borrower 5. program_switch 6. structure_change Lower DTI or higher qualifying income
Cash-to-Close Path cash_to_close 1. incentive_dpa 2. incentive_cra 3. gift_funds 4. seller_concession 5. seller_buydown 6. lower_down_payment 7. asset_strategy Reduce cash required at closing
Payment Path payment 1. rate_improvement 2. credit_tier_optimization 3. program_switch 4. buydown_temp 5. buydown_permanent 6. arm_structure 7. longer_term Lower monthly payment
Credit Path credit 1. error_correction 2. utilization_reduction 3. rapid_rescore 4. authorized_user 5. program_switch_to_fha 6. wait_path Improve score or access lower-threshold program
Property Path property 1. alternative_property_type 2. alternative_geography 3. tract_incentive 4. multi_unit_rental_offset 5. lower_hoa_tax Change property assumptions to improve eligibility
Program Path program 1. program_switch 2. portfolio_exception 3. non_qm_path 4. future_ready_plan Find eligible program or build path to eligibility
Timing Path timing 1. score_improvement_plan 2. debt_reduction_plan 3. savings_accumulation_plan 4. monitoring_activation Generate Action Plan with milestones and re-qualification trigger
7D. Scenario Ranking Rules Rule ID Rule Name Ranking Logic Notes
Goal Alignment Score WEIGHTED_SUM: payment_score * goal_priority_payment + cash_score * goal_priority_cash + purchase_power_score * goal_priority_purchase_power + wealth_score * goal_priority_wealth + speed_score * goal_priority_speed All weights normalized to 0-1. This is the primary ranking signal.
Approval Confidence Multiplier Composite score: (FICO_margin * 0.30) + (DTI_margin * 0.30) + (LTV_safety * 0.20) + (documentation_completeness * 0.20) Applied as multiplier. 0.85+ = high confidence. <0.60 = human review flag.
Cash Feasibility Penalty IF projected_cash_to_close > funds_available_for_closing THEN score * 0.50 Infeasible scenarios must be deprioritized even if economics are strong.
Payment Comfort Penalty IF projected_pitia > target_monthly_payment THEN score * (1 - overage_pct * 0.5) Gradual penalty. Scenario is not eliminated but ranks lower.
Complexity Penalty high_complexity * -0.15 | medium_complexity * -0.05 | low_complexity * 0 Borrowers prefer simpler paths. Complexity penalty is modest but real.
Wealth Outcome Bonus IF total_interest_estimate < baseline_total_interest THEN + (interest_savings / baseline * 0.10) Rewards long-term savings when borrower’s goal_priority_wealth ≥ 3.
Tier Assignment Safe: highest confidence_score. Optimal: highest weighted_composite_score. Transformational: highest economic benefit among action-required scenarios. Every deal gets a Safe. Optimal is always different from Safe. Transformational is optional.
The following calculations must be implemented consistently across all engine components. These are the mathematical primitives the engine runs on.
// PMT: Monthly payment given rate, term, loan amount
PMT(annual_rate, term_months, loan_amount) {
r = annual_rate / 12
return r * loan_amount / (1 - (1 + r)^(-term_months))
}// PV: Max loan amount given payment, rate, term (inverse PMT)
PV(annual_rate, term_months, monthly_payment) {
r = annual_rate / 12
return monthly_payment * (1 - (1 + r)^(-term_months)) / r
}// NPER: Solve for term given rate and payment (inverse PMT for n)
NPER(annual_rate, monthly_payment, loan_amount) {
r = annual_rate / 12
return -LN(1 - r * loan_amount / monthly_payment) / LN(1 + r)
}// TOTAL_INTEREST: Lifetime interest cost
TOTAL_INTEREST(monthly_payment, term_months, loan_amount) {
return (monthly_payment * term_months) - loan_amount
}// RECAPTURE_MONTHS: Closing cost breakeven
RECAPTURE_MONTHS(closing_costs, monthly_savings) {
return closing_costs / monthly_savings
}Metric Formula Fannie Mae Thresholds Front-End DTI (Housing Ratio) PITIA ÷ Gross Monthly Income Max 28% (guideline); up to 36% manual Back-End DTI (Total DTI) (PITIA + All DTI Obligations) ÷ GMI 36% manual / 45% conditional / 50% DU automated
P+I + monthly_tax + monthly_insurance + hoa_monthly + mi_monthly All components required for accurate DTI Student Loan DTI Treatment If deferred: 0.5% of balance. If IDR: actual payment (or 0.5% if < actual) Fannie Mae B3-6-05 (Dec 2025) Installment Exclusion Debts with ≤10 payments remaining MAY be excluded from DTI Lender discretion. Document remaining term.
LTV Range PMI Required Rate Impact Notes ≤80.00% No Best / par 80% is the key threshold. Calculate exact dollar to reach it. 80.01%-90.00% Yes (or piggyback) +Slight Conventional PMI or 80/10/10 piggyback strategy. 90.01%-95.00% Required +Moderate Standard 5-10% down conventional range. 95.01%-96.50% Required +Higher FHA 3.5% down. PMI = MIP. Life-of-loan if LTV > 90%. 96.51%-100% Funded / Guarantee Program-specific VA: funding fee. USDA: guarantee fee. No monthly PMI.
FICO Band Rate Adjustment PMI Tier Engine Action 760+ Par (best pricing) Tier 1 (lowest) No optimization needed on credit. Focus on other dimensions. 740-759 +0.125% to +0.25% Tier 2 Calculate cost of reaching 760. Model savings. 720-739 +0.25% to +0.50% Tier 3 Credit optimization has high ROI here. 700-719 +0.50% to +0.75% Tier 4 FHA may be competitive. Model both. 680-699 +0.75% to +1.00% Tier 5 FHA often wins on total cost. Rapid Rescore high priority. 640-679 +1.00%+ Tier 6 FHA primary. VA if eligible. Utilization paydown = fastest path up. 580-639 FHA floor only N/A conventional FHA 3.5% or VA only. Priority: get to 640 for better rate access. < 580 No standard program — Non-QM or portfolio only. Action plan required.
Entity MVP Required Fields Phase 2 Fields Borrower id, name, flags (veteran, FTB, self-employed), goal weights, target payment/cash Date of birth, citizenship, household size for USDA/DPA income limits IncomeSource income_type, gross_monthly, qualifying_monthly, history_months, documentation_status add_back_amount, gross_up details, boarder income, complex averaging Liability type, balance, monthly_payment, months_remaining, include_in_dti, eligible_for_payoff interest_rate (for consolidation ranking), cosigned/business debt logic Asset type, balance, liquid_flag, eligible_for_closing, eligible_for_reserves, haircut_pct seasoning_days, gift_letter, crypto liquidation workflow Property address, county, type, occupancy, unit_count, purchase_price/value, taxes, insurance, HOA census_tract, flood_zone, AVM confidence, condo project status Deal deal_type, borrower_id, property_id, intent, closing_costs, seller_concession, current_balance/payment desired_cash_out, complex refi scenarios, multi-property Program All core qualification parameters: score, LTV, DTI, reserves, property types, occupancy, MI, DPA flags pricing feeds (Optimal Blue/Polly), overlays, CRA-specific rules Incentive type, geography, max_benefit, eligibility logic, combinable_flag, funding_status Complex stacking rules, employer-specific programs, dynamic funding checks Scenario All financial outcomes + compliance_status + approval_confidence + valid_flag Learning from funded outcomes, advanced scenario tagging Recommendation All tier scenario IDs, key_moves, recommended_next_step, confidence_summary Multi-session recommendation tracking, advisor annotation Explanation All five plain-language fields + disclosure_text Multi-channel output formatting (voice, email, SMS) AuditEvent All fields. Non-negotiable. Enhanced monitoring hooks, ML model audit trails
Do not build a giant all-knowing underwriting machine. Start with a smaller, precise promise: Diagnose the borrower’s primary financing blockers → generate a limited but high-value set of optimization scenarios → explain the best next path clearly. That loop, working end-to-end with full audit logging and fair lending compliance, is the MVP.
1 Borrower + Property + Deal canonical objects with all MVP required fields
2 Baseline Eligibility Engine: 7 programs, parallel, full output schema
3 Constraint Detection Engine: all 8 constraint types with severity and routing
4 Optimization Move Library: 20-30 highest-impact moves, all fields per spec
5 DPA / Incentive database: county-indexed, auto-match to borrower profile
6 Scenario Generation Engine: composable framework, valid_flag filtering
7 Scenario Ranking Engine: goal-weighted scoring, tier assignment
8 Recommendation Engine: Safe / Optimal / Transformational output object
9 Explanation Layer: all five plain-language fields, Nova-consumable
10 Audit & Compliance Log: immutable event logging, disparate impact hook
11 Nova MVP: 5 core conversation paths consuming Explanation objects
12 Advisor Dashboard: borrower snapshot, top 3 recs, audit trail view
Define the canonical deal state • Test baseline eligibility • Detect blockers Apply optimization moves • Generate scenarios • Rank against borrower purpose Explain in plain language • Log everything.
Document: Clarity Engine Data Dictionary + Rules Matrix v1.0 | Companion: Architecture Blueprint v1.0, Master PRD v1.0 | CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. (d/b/a Purlend)