Mortgage Math Module BIX Implementation Guide
PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend Engineering Reference | Gear 1 Sprint Version 1.0 | March 2026
This document is the authoritative BIX engineering reference for the Clarity Engine Mortgage Math Module — the calculation engine at the core of the Clarity Engine decision stack.
The Mortgage Math Module is a shared computation library. Every family-specific underwriting module (Conventional, FHA, VA, DSCR) calls this library for all numerical computation. The library produces deterministic, reproducible outputs with full intermediate steps — required by the Clarity Ledger for decision lineage recording.
The math module sits at Layer 2 of the Clarity Engine stack:
Layer Component Calls Math Module? Layer 1 Borrower Intelligence Ledger (data primitive) No — feeds inputs to Layer 2 Layer 2 Mortgage Math Module (this document) N/A — IS the math layer Layer 3 Family Underwriting Modules (VA, FHA, Conv, DSCR) Yes — calls this library Layer 4 Control / Validation Layer Yes — re-verifies key computations Layer 5 Nova (borrower-facing output) Yes — requests plain language translations Layer 6 Clarity Ledger (decision lineage) Yes — receives lineage records from every call
The math module exposes 21 functions organized into 6 categories. Each function has a unique stable ID used by the Clarity Ledger for lineage recording.
Function ID Name Category Called By
Monthly Payment (PMT) Core All families
Present Value / Max Loan Core All families
Term Solve Core All families
Future Value Core Analysis
Rate Solve Core Analysis
Debt-to-Income Ratio Qualifying Conv, FHA, VA
Gross Monthly Income Qualifying Conv, FHA, VA
Monthly PITI Qualifying All families
Collateral All families
Amortization Schedule Analysis All families
2-1 Temporary Buydown Optimization Conv, FHA, VA
Discount Point Breakeven Optimization All families
Recapture Period Optimization All families
Payment Delta Comparison All families
Cash-Out Available Equity Conv, FHA, VA
Reserves Calculator Assets Conv, DSCR
Credit Utilization Credit All families
Debt Service Coverage Ratio
DSCR only
Cash-to-Close Stack Closing All families
FHA MIP (Upfront + Annual) FHA FHA only
Conventional PMI Estimate Conventional Conv only
Every function in the math module conforms to the same input/output envelope. BIX must implement this envelope exactly — it is the interface the Clarity Ledger uses to record lineage.
{ "function_id": "MATH-PMT-001", // Required: stable function ID "version": "1.0", // Required: module version "call_context": { "borrower_id": "string | null", // Ledger link (null = anonymous) "session_id": "string", // Tracing ID for this computation session "called_by": "VA_UNDERWRITING_AGENT", // Which agent invoked this function "call_reason": "qualification_check" // Why this function was called }, "inputs": {
// Function-specific inputs — see Section 4 for each function
}}
{ "function_id": "MATH-PMT-001", "version": "1.0", "status": "success | error | validation_warning", "outputs": {
// Function-specific outputs — see Section 4 for each function
},
"computation_trace": [
{ "step": 1, "label": "monthly_rate", "formula": "0.0675 / 12", "result": 0.005625 },
{ "step": 2, "label": "term_months", "formula": "30 * 12", "result": 360 },
{ "step": 3, "label": "pmt_raw", "formula": "PMT formula", "result": 2748.486 },
{ "step": 4, "label": "pmt_rounded", "formula": "ceil to cent", "result": 2748.49 }
],
"lineage_record": {
"input_hash": "sha256 of canonical input JSON",
"output_hash": "sha256 of canonical output JSON",
"rounding_policy": "ROUND_UP_CENT",
"timestamp": "ISO 8601",
"deterministic": true
},
"nova_text": "string | null", // Plain language output for borrower UI
"validation_flags": [], // Array of warning objects (see Section 5)
"errors": [] // Array of error objects (see Section 5)
}CRITICAL: The computation_trace array must contain every intermediate step in order. This is not optional logging — it is the lineage record that the Clarity Ledger stores. Never skip steps or batch-compute without recording the trace.
Each specification below provides: the formula in pseudocode, all required and optional inputs with types and validation rules, the output schema, a worked example with exact numeric output, edge cases, and the rounding policy applied.
Formula monthly_rate = annual_rate / 12 term_months = term_years * 12 numerator = monthly_rate * (1 + monthly_rate) ^ term_months denominator = (1 + monthly_rate) ^ term_months - 1 pmt_raw = loan_amount * (numerator / denominator) pmt = CEIL(pmt_raw, 0.01) // Round UP to nearest cent
Inputs Parameter Type Validation Notes loan_amount decimal > 0 Principal balance annual_rate decimal > 0 and < 0.30 e.g., 0.0675 for 6.75%. Flag if > 0.15 term_years integer 1 – 40 Typically 10, 15, 20, 25, or 30
Outputs Field Type Rounding Description monthly_pi decimal CEIL to nearest $0.01 Fixed monthly principal + interest term_months integer Exact term_years × 12 monthly_rate decimal 10 decimal places internally annual_rate / 12
Worked Example — BIX Test Vector TV-PMT-001 INPUT: loan_amount=425000 annual_rate=0.0675 term_years=30
Step 1: monthly_rate = 0.0675 / 12 = 0.0056250000 Step 2: term_months = 30 * 12 = 360 Step 3: (1 + monthly_rate)^360 = (1.005625)^360 = 7.6860857... Step 4: numerator = 0.005625 * 7.6860857 = 0.0432342... Step 5: denominator = 7.6860857 - 1 = 6.6860857 Step 6: pmt_raw = 425000 * (0.0432342 / 6.6860857) = 425000 * 0.0064668... = 2748.4891... Step 7: pmt = CEIL(2748.4891, 0.01) = 2748.49
EXPECTED OUTPUT: monthly_pi = 2748.49
Edge Cases
Formula monthly_rate = annual_rate / 12 term_months = term_years * 12 discount_factor = (1 - (1 + monthly_rate)^(-term_months)) / monthly_rate max_loan = FLOOR(target_monthly_payment * discount_factor, 1.00) // Down to dollar
Worked Example — BIX Test Vector TV-PV-001 INPUT: target_monthly_payment=2528 annual_rate=0.0575 term_years=30
Step 1: monthly_rate = 0.0575 / 12 = 0.0047916... Step 2: term_months = 360 Step 3: (1.004792)^-360 = 0.17317... Step 4: discount_factor = (1 - 0.17317) / 0.004792 = 172.5578... Step 5: max_loan_raw = 2528 * 172.5578 = 436,226.12... Step 6: max_loan = FLOOR(436226.12, 1.00) = 436226
EXPECTED OUTPUT: max_loan_amount = 436226 cash_available (if current balance = 391400): 436226 - 391400 = 44826
Formula front_end_dti = monthly_housing_payment / gross_monthly_income back_end_dti = (monthly_housing_payment + monthly_debt_obligations) / gross_monthly_income dti_gap = back_end_dti - dti_limit // Negative = under limit (PASS) dti_headroom = (gross_monthly_income * dti_limit) - (monthly_housing_payment + monthly_debt_obligations)
Liability Inclusion Rules — Hardcoded Logic Debt Type Include? Flag Code Notes Revolving minimums (credit cards) YES — Always include Installment loans (auto, student) YES — Always include unless exclusion applies Installment ≤10 payments remaining NO
Exclude and record flag Co-signed, 3rd party pays ≥12 months NO
Require documentation Business debt on business return + CPA letter NO
Require documentation Deferred student loans (FHA/Conv) YES at 1% balance
Use 1% of balance if no payment Deferred student loans (VA) NO if deferred > 12 months
Per VA Chapter 4 Lease payments YES — Always include
DTI Limit Reference Table Program Front-End Back-End Limit Override Path Conventional (manual) 28% guideline 36% hard / 45% with conditions Strong credit / reserves Conventional (DU/LP automated) No limit 50% maximum AUS approval FHA No hard limit 43% standard 57% with strong compensating factors VA No limit 41% benchmark — NOT hard stop 120% residual income test
N/A N/A — uses DSCR ratio Property cash flow only
Worked Example — BIX Test Vector TV-DTI-001
gross_monthly_income = 8500 monthly_housing_payment = 2847 (PITI from MATH-PITI-001) monthly_debt_obligations = 640 (auto 340 + CC minimums 300) dti_limit = 0.45 (conventional with conditions)
Step 1: front_end_dti = 2847 / 8500 = 0.33494... → 33.5% Step 2: total_obligations = 2847 + 640 = 3487 Step 3: back_end_dti = 3487 / 8500 = 0.41023... → 41.0% Step 4: dti_gap = 0.41023 - 0.45 = -0.03977 → PASS Step 5: dti_headroom = (8500 * 0.45) - 3487 = 3825 - 3487 = 338.00
front_end_dti: 33.5% back_end_dti: 41.0% result: PASS dti_headroom: 338.00 (additional monthly obligations before hitting limit)
GMI is the most complex computation in the module. Different income types follow different calculation rules. BIX must implement each income type as a separate sub-function and aggregate at the end.
Income Type Formulas Income Type Formula Documentation Trigger W-2 Salary / Hourly annual_salary / 12 VOE + 30-day paystubs Bonus / Overtime / Commission (year1 + year2) / 24 (2-yr average) 2-year history required; flag declining trend Self-Employed (Schedule C) ((net_profit + add_backs) yr1 + yr2) / 24 2-yr avg; add depreciation, depletion, mileage, home office back Rental Income gross_rent * 0.75 / 12 (25% vacancy) Executed lease or market rent appraisal SS / Pension / Disability (non-taxable) for DTI monthly_amount * 1.25 Award letter; tax_free flag = true SS / Pension / Disability for VA Residual monthly_amount (NO gross-up) Different variable from DTI gross — see VA Module Asset Depletion (liquid + 0.60 * retirement) / term_months Program-specific; flag asset_depletion_used = true Boarder Income (FHA only) monthly_rent * 0.75 (if <= 30% of total GMI) 12-month history required
CRITICAL — VA Income Split: VA requires TWO separate income calculations for the same borrower. (1) Gross income for DTI — includes gross-up for non-taxable income at 1.25x. (2) Net income for residual — no gross-up, use actual net. These are different variables. Do NOT reuse one for the other. See VA Module PRD v1.0 for full specification.
Worked Example — BIX Test Vector TV-GMI-001 INPUT: Borrower has three income streams:
Context: DTI calculation (not VA residual)
Step 1 (W-2): 82000 / 12 = 6833.33 Step 2 (OT avg): (8400 + 9600) / 24 = 18000 / 24 = 750.00 Step 3 (SS DTI): 880 * 1.25 = 1100.00 [gross-up applied, tax_free=true] Step 4 (total): 6833.33 + 750.00 + 1100.00 = 8683.33
gmi_total: 8683.33 gross_up_applied: true gross_up_streams: [{type:'SS', amount:880, factor:1.25, gmi_contribution:1100}] income_breakdown: [{type:'W2', gmi:6833.33}, {type:'OT', gmi:750.00}, {type:'SS', gmi:1100.00}]
Formula PITI = P_and_I + property_tax_monthly + hazard_insurance_monthly + hoa_monthly + mi_or_mip_monthly
property_tax_monthly = annual_property_tax / 12 hazard_insurance_monthly = annual_hazard_insurance / 12
Worked Example — BIX Test Vector TV-PITI-001
P&I: 2424 (from MATH-PMT-001) annual_property_tax: 8400 annual_insurance: 1800 hoa_monthly: 0 pmi_monthly: 184 (from MATH-MI-001)
Step 1: tax_monthly = 8400 / 12 = 700.00 Step 2: ins_monthly = 1800 / 12 = 150.00 Step 3: PITI = 2424 + 700 + 150 + 0 + 184 = 3458.00
EXPECTED OUTPUT: monthly_piti = 3458.00 component_breakdown: {pi:2424, tax:700, insurance:150, hoa:0, mi:184}
Formulas LTV = first_mortgage_balance / property_value CLTV = (first_mortgage + heloc_balance + second_mortgage) / property_value HCLTV = (first_mortgage + full_heloc_line_limit + second_mortgage) / property_value
// For purchase: first_mortgage_balance = purchase_price - down_payment
PMI / MIP Threshold Flags (Auto-Set on Every LTV Computation)
Flag
Condition
Action
pmi_required
LTV > 80% AND loan_type = conventional
Set true; pass to MATH-MI-001
pmi_cancellation_ltv
LTV <= 80%
Record balance at which PMI cancels
pmi_auto_cancel_ltv
LTV <= 78% on original schedule
Homeowners Protection Act auto-cancel
fha_mip_required
loan_type = FHA
Always true regardless of LTV
va_no_pmi
loan_type = VA
Always true — set pmi_required = false
high_balance_eligible
first_mortgage > conforming limit
Check county limit tableFormula DSCR = monthly_gross_rent / monthly_pitia
monthly_pitia = P&I + property_tax + insurance + hoa // NO personal DTI for DSCR
DSCR Tier Logic DSCR Range Tier Label BIX Flag Typical Lender Response >= 1.25 Strong
Approve at standard terms 1.20 – 1.24 Good
Approve at standard terms 1.10 – 1.19 Acceptable
May require larger reserve 1.00 – 1.09 Break-Even
25–30% down often required 0.75 – 0.99 Negative Cashflow
Select lenders only, higher rate < 0.75 Ineligible
Return ineligible flag
Worked Example — BIX Test Vector TV-DSCR-001
purchase_price: 375000 down_payment: 93750 loan: 281250 annual_rate: 0.07875 term_years: 30 monthly_rent: 2650 tax: 420 insurance: 130 hoa: 0
Step 1: P&I = PMT(281250, 0.07875, 30) = 2033.91 Step 2: PITIA = 2033.91 + 420 + 130 + 0 = 2583.91 Step 3: DSCR = 2650 / 2583.91 = 1.02558... → 1.03 (2 decimal places) Step 4: tier = Break-Even (1.00 ≤ 1.03 < 1.10)
dscr: 1.03 tier: DSCR_BREAKEVEN monthly_cashflow: 2650 - 2583.91 = 66.09
Formula upfront_mip = base_loan_amount * 0.0175
// Annual MIP rate by LTV and term (current FHA schedule):
// LTV > 90% AND term > 15yr: 0.0055
// LTV <= 90% AND term > 15yr: 0.0050
// LTV > 78% AND term <= 15yr: 0.0015
// LTV <= 78% AND term <= 15yr: 0.0000
annual_mip = base_loan_amount * annual_mip_rate
monthly_mip = annual_mip / 12
// Cancellation logic:
// IF ltv_at_origination > 0.90: mip_cancellation = 'LIFE_OF_LOAN'
// IF ltv_at_origination <= 0.90: mip_cancellation = 'YEAR_11'
IMPORTANT: FHA MIP does NOT cancel at 80% LTV. This is a common mistake. The cancellation rules are based on LTV AT ORIGINATION, not current LTV. BIX must not apply the conventional PMI cancellation logic to FHA loans.PMI Rate Matrix Credit Score
760+ 0.19% 0.26% 0.36% 0.46% 740–759 0.23% 0.32% 0.43% 0.54% 720–739 0.31% 0.41% 0.55% 0.65% 700–719 0.44% 0.57% 0.71% 0.83% 680–699 0.56% 0.72% 0.88% 1.05% 660–679 0.77% 0.95% 1.16% 1.37%
Monthly PMI = (loan_amount × annual_pmi_rate) / 12 monthly_pmi = ROUND((loan_amount * annual_pmi_rate) / 12, 0.01)
Note: These are estimated rates for modeling. Actual PMI is quoted by the PMI insurer at origination. BIX should label all PMI output as 'estimated' until a live quote is available.
Formula year1_rate = note_rate - 0.02 year2_rate = note_rate - 0.01 year3_rate = note_rate
pmt_note = PMT(loan_amount, note_rate, term_years) // Qualify at this rate pmt_year1 = PMT(loan_amount, year1_rate, term_years) pmt_year2 = PMT(loan_amount, year2_rate, term_years)
subsidy_yr1 = (pmt_note - pmt_year1) * 12 subsidy_yr2 = (pmt_note - pmt_year2) * 12 buydown_fund = subsidy_yr1 + subsidy_yr2
Qualifying Rate: Borrower must qualify at note_rate (7.25%), NOT at the reduced year-1 rate (5.25%). BIX must pass note_rate to MATH-DTI-001, not year1_rate.
Component Order (Required) Component Formula / Default Notes Down payment purchase_price * down_pct Always first Origination fee loan_amount * origination_pct (default 0.0075) Use actual if provided Title and escrow Flat input (default $2,500) Property-value dependent Appraisal Flat input (default $650) SFR standard Credit report Flat input (default $65)
Prepaid interest daily_interest * days_to_month_end daily_interest = (loan * rate) / 365 Prepaid hazard insurance annual_insurance * 14 / 12 14 months upfront standard Escrow setup — tax monthly_tax * escrow_months (default 3) Varies by close month Upfront MIP/funding fee Only if NOT financed FHA: 1.75%, VA: per funding fee table Other fees Sum of recording, transfer tax, etc.
LESS: Seller concessions negative amount Program caps apply LESS: Lender credits negative amount From rate adjustment LESS: DPA grants negative amount Applied grants LESS: Earnest money negative amount Already paid
Rounding is applied ONLY to final outputs. All intermediate computation carries full floating-point precision. Rounding intermediate values accumulates error and is a critical bug class to avoid.
Value Type Policy Function(s) Monthly payment (PMT) ROUND UP (ceiling) to nearest $0.01
Loan amount / max loan ROUND DOWN (floor) to nearest $1.00
Interest rate (periodic) Carry 10 decimal places internally; display 4 All rate-using functions DTI ratio Display as percentage, 1 decimal (e.g., 43.2%)
Display as percentage, 2 decimal (e.g., 89.74%)
Dollar savings / delta ROUND to nearest $1.00
Funding fee / MIP amount ROUND to nearest $1.00 MATH-MIP-001, VA funding fee Breakeven months ROUND UP to nearest whole month
DSCR ratio 2 decimal places (e.g., 1.03)
Monthly PMI/MIP ROUND to nearest $0.01
All intermediate values Full floating-point precision — never round All functions
Code Trigger Condition Required Response
annual_rate = 0 or negative Return error; do not compute
loan_amount <= 0 Return error; do not compute
term_years outside 1–40 Return error; do not compute
gross_monthly_income = 0 in DTI calculation Return error; do not divide by zero
property_value = 0 in LTV calculation Return error; do not divide by zero
monthly_pitia = 0 in DSCR calculation Return error; do not divide by zero
Function called with missing required input Return error listing missing fields
Code Trigger Condition Flag in Output
annual_rate > 15% Unusually high rate — verify input
DTI > 50% (all programs) Exceeds all standard program limits
Underwater — verify property value and balance
Below minimum DSCR threshold for most programs
Overtime income trending down year-over-year Flag for underwriter review
Asset depletion income used Program-specific; not universally accepted
Reserves below 2 months PITI May fail conventional reserve requirement
Installment debt with ≤10 payments remaining excluded Record which debt excluded and why
Co-signed debt excluded (3rd party payment documented) Require 12 months bank statements
Business debt excluded via CPA letter Require CPA letter in file
These are confirmed bug classes from prior mortgage calculation systems. BIX must implement safeguards against each.
# Prohibited Pattern Why It Fails Correct Approach 1 Apply annual_rate directly in PMT without dividing by 12 Produces a wildly wrong payment — rate must be periodic (monthly) Always: monthly_rate = annual_rate / 12 2 Round intermediate values before final output Accumulates rounding error across multi-step computations Carry full precision; round only at final step 3 Reuse DTI gross income for VA residual income VA requires net income for residual, gross for DTI — different variables Maintain separate gmi_for_dti and net_income_for_residual 4 Apply FHA 80% LTV MIP cancellation to FHA loans FHA MIP does not cancel at 80% LTV — it cancels at year 11 or never FHA MIP cancellation is origination-LTV-based, not payment-schedule-based 5 Apply 4% seller concession cap to all VA closing costs The 4% cap applies to concessions only, not standard closing costs Standard closing costs are not subject to the 4% cap 6 Use note_rate - 1% for buydown qualifying DTI Borrower qualifies at note_rate, not the temporary reduced rate Pass note_rate to DTI check, never year1_rate or year2_rate 7 Apply conventional DTI 41% hard stop to VA loans VA DTI 41% is a benchmark that triggers the residual income test — not a hard denial VA DTI > 41%: trigger MATH-VA-RESIDUAL, do not auto-deny 8 Use DSCR property PITIA for borrower DTI computation DSCR loans qualify on property cash flow, not borrower DTI For DSCR: call MATH-DSCR-001 only; do not call MATH-DTI-001 9 Apply 100% of retirement account balance to reserves Standard is 60% of vested balance reserves_eligible = liquid + (retirement_vested * 0.60) 10 Cache PMT by (loan_amount, annual_rate) only term_years changes the payment; must be part of the cache key Cache key: (loan_amount, annual_rate, term_years)
Every math function call must emit a lineage record to the Clarity Ledger. This is non-negotiable — it is the mechanism by which the Clarity Engine achieves auditability, reproducibility, and regulatory defensibility.
{ "ledger_event_type": "MATH_COMPUTATION", "function_id": "MATH-PMT-001", "version": "1.0", "timestamp": "2026-03-15T14:32:11Z", "borrower_id": "BRW-00412", // null if anonymous "session_id": "SES-20260315-0041", "called_by": "VA_UNDERWRITING_AGENT", "call_reason": "qualification_check", "inputs_canonical": { ...inputs in sorted key order }, "input_hash": "sha256 of inputs_canonical", "outputs_canonical": { ...outputs in sorted key order }, "output_hash": "sha256 of outputs_canonical", "computation_trace": [ ...all intermediate steps ], "rounding_policy": "ROUND_UP_CENT", "deterministic": true, "phase1_hash": "sha256 of entire record — for blockchain Phase 1" }
Every call to the same function with the same inputs must produce identical outputs and an identical input_hash. This is required for reproducibility and replay. BIX must not use any non-deterministic computation (random seeds, timestamps embedded in computation, floating-point hardware variation) in the calculation path.
In Phase 1, every lineage record receives a SHA-256 hash of the complete record (phase1_hash). This hash can be stored in a blockchain in Phase 2 without re-architecting. BIX should implement the hashing now even if blockchain anchoring is deferred. phase1_hash = SHA256(JSON.stringify(lineage_record_without_phase1_hash))
// Canonical JSON: sorted keys, no whitespace
9. ACCEPTANCE TEST VECTORS
BIX must reproduce every test vector below exactly before the math module is considered Gear 1 complete. These are the canonical reference outputs derived from the verified Pro_Calc.xlsx workbook.
Vector ID
Function
Key Inputs
Expected Output
Source
TV-PMT-001
MATH-PMT-001
$425K, 6.75%, 30yr
monthly_pi = $2,748.49
Pro_Calc.xlsx
TV-PMT-002
MATH-PMT-001
$391.4K, 5.75%, 30yr
monthly_pi = $2,284.39
Pro_Calc.xlsx
TV-PMT-003
MATH-PMT-001
$391.4K, 7.25%, 27yr
monthly_pi = $2,758.34
Pro_Calc.xlsx
TV-PV-001
MATH-PV-001
Pmt=$2,528, 5.75%, 30yr
max_loan = $436,226
Pro_Calc.xlsx
TV-DTI-001
MATH-DTI-001
GMI=$8,500, Housing=$2,847, Debts=$640, Limit=45%
back_end=41.0%, PASS, headroom=$338
Derived
TV-DSCR-001
MATH-DSCR-001
Rent=$2,650, PITIA=$2,583.91
dscr=1.03, tier=DSCR_BREAKEVEN
Derived
TV-LTV-001
MATH-LTV-001
Purchase=$500K, Down=$50K
LTV=90.00%, pmi_required=true
Derived
TV-BUYDOWN-001
MATH-BUYDOWN-001
$400K, 7.25%, 30yr
buydown_fund=$9,441.72, yr1=$2,209.29
Derived
TV-MIP-001
MATH-MIP-001
$320K loan, LTV=96.5%, 30yr
upfront=$5,600, monthly=$146.67, cancel=LIFE_OF_LOAN
Derived
TV-RECAPTURE-001
MATH-RECAPTURE-001
Old=$2,847, New=$2,528, Costs=$6,400
monthly_savings=$319, recapture=21 months
Pro_Calc.xlsx
Delivery Gate: All 10 test vectors must pass before BIX submits the math module for Gear 1 review. Include the computation_trace in each test output so David can verify the intermediate steps, not just the final number.
10. CLAUDE SKILL INTEGRATION
The Mortgage Math Module has a corresponding Claude skill: Clarity_Engine_Math_SKILL.md. BIX and Claude are parallel implementations of the same specification — not alternatives.
Dimension
Claude Math Skill
BIX Math Module
Primary use
Real-time consultation, scenario modeling, borrower explanation
Production computation, API service, Clarity Ledger integration
Input method
Natural language + structured
JSON API via request envelope
Output format
Structured computation block + Nova plain language
JSON response envelope + lineage record
Lineage recording
Includes lineage record block in output (format only)
Writes actual lineage record to Clarity Ledger
Test vectors
Same vectors — manually verifiable
Same vectors — automated CI/CD test suite
Rounding policy
Same policy — stated explicitly in output
Same policy — enforced in code
Prohibited patterns
Same list — guards against these in reasoning
Same list — enforced via unit tests
Source of truth
This BIX guide is canonical — Claude skill is a training document pointing to same spec
This BIX guide is canonical — BIX implements exactly this spec
When David uses the Claude skill to model a scenario and then routes the same scenario to BIX for production computation, the outputs must be identical within the rounding policy. Any divergence is a defect.
11. GEAR 1 SPRINT CHECKLIST
This is the BIX Gear 1 completion checklist for the Mortgage Math Module.
#
Deliverable
Owner
Acceptance Criteria
1
Implement all 21 math functions
BIX
All TV- test vectors pass exactly
2
Implement universal request/response envelope
BIX
All calls conform to Section 3 schema
3
Implement computation_trace in every response
BIX
All intermediate steps present in order
4
Implement lineage_record in every response
BIX
input_hash and output_hash verified reproducible
5
Implement phase1_hash (SHA-256)
BIX
Hash is deterministic — same inputs, same hash
6
Implement all error codes (ERR-MATH-001 through 007)
BIX
Error returned, not exception, for each trigger condition
7
Implement all warning codes
BIX
Warnings in validation_flags array, computation continues
8
Implement liability exclusion flags (EXCL-10PMT, EXCL-COSIGN, EXCL-BIZ)
BIX
Excluded debts removed from monthly_debt_obligations with flag recorded
9
Implement VA income split (gross for DTI vs net for residual)
BIX
Two separate variables — verified against VA Module PRD v1.0 TC01–TC10
10
Pass all 10 acceptance test vectors (Section 9)
BIX
Output matches expected to cent
11
Submit computation_trace for each test vector to David for review
BIX
Intermediate steps verified, not just final number
12
No prohibited patterns (Section 7) present in implementation
BIX + David review
Code review against Section 7 checklist— End of Document — CONFIDENTIAL — PreFi, Inc. / Purpose Technology, Inc. d/b/a Purlend