Data room / The current model

Model map

Notes, 611 words, about 3 min to read

Where every number comes from, and the rule that none is typed by hand.

docs/MODEL_MAP.md Open the file as written

Model map: where every Equity Flow number comes from

Written for EQUITY_FLOW_FIXES.md, section 0.1. Read this before touching a number.

What was found (before the fixes)

Four code paths produced Equity Flow numbers, and they disagreed with each other:

Path What it produced Product it modeled Status
Inline JS in public/equity-flow.html (RATE, FEE_PCT, efBal, maxMonths, drawAtCeiling) The live calculator Fixed-rate deferred-interest second lien, CLTV 60% / 75% box The only live model; stories and investor table were typed by hand and had drifted from it
Hand-typed HTML in public/equity-flow.html Five homeowner stories, the investor economics table, the "~18M" cohort Same product, at 3% HPI (stories) and 4% HPI (chart) Not rendered from any code; no drift check
Inline JS in public/equity.html (efRate, efFeePct, efBalance10) The Equity Flow column on the Equity Tap comparison Same product, lump-sum variant, no fee floor Second copy of the pricing constants
server/prompts.js + server/tools.js (EQUITY_FLOW_* prompts, model_equity_flow_offer, calculate_equity_flow_scenarios, estimate_market_opportunity, model_portfolio_returns) and /api/analyze-equity-flow* in server/index.js AI analyses The discontinued appreciation-share product (25% share, ride-along ratchet, "no debt, no interest") Dead: no page called the endpoints. Contradicted the site. Removed.
product-diligence/models/equity_flow_model.py and product-diligence/concepts/line_funding_model.py (gitignored) Stage-4 diligence grids Appreciation-share product (v1) and the open credit line (v2.1) Historical diligence artifacts for rejected versions; not site inputs. Left in place, untouched.

What there is now: one model

model/config.js        every parameter, with its source or verification note (VERIFY_LIST)
model/contract.js      the contract term model the invariant tests read
model/equity_flow.js   the model: amortization, fees, balances, constraints, HECM fit,
                       max deposit, projections, closing package, alternatives,
                       investor cash flows and IRR
model/stories.js       the five stories as inputs; computeStories() refuses any that fail
data/cohort_funnel.js  the serviceable cohort from cited inputs
data/sources.js        every citation used on the site
scripts/build_site.js  renders model output into the pages and docs/OPEN_ITEMS.md
tests/                 invariants, acceptance cases, drift

The model is plain ESM with no dependencies, so it runs in two places from one file:

  • Browser. server/index.js serves model/ at /model/. public/equity-flow.html imports /model/equity_flow.js for the calculator; public/equity.html imports it for the Equity Flow column (lumpSumBalance) and the qualification check (CONFIG.max_start_cltv).
  • Build. npm run build runs scripts/build_site.js in Node, which imports the same file and renders every model-derived fragment into public/equity-flow.html, public/investors.html, public/about.html, and public/index.html:
    • block fragments between <!-- BUILD:key --> and <!-- /BUILD:key --> (stories, investor table, underwriting row, funnel tables, citations);
    • inline values inside any element with data-build="key" (cohort figures, coupon, fee floor, ages, HomeSafe rate, occupancy definition);
    • citation numbers in <a class="cite" data-cite="key">.
  • Tests. npm test runs node --test tests/:
    • tests/invariants.test.js: the contract stays a Reg Z reverse mortgage (section 0.2); the cash-flow model never takes a payment before an exit; the pages contain no due-date or balloon language.
    • tests/model.test.js: the acceptance cases from sections 1, 2, 3, 6, 9, with the numbers recorded in CHANGELOG_FIXES.md.
    • tests/drift.test.js: buildAll({ check: true }) must report no drift, so a hand-typed number cannot survive.

Rules

  1. A number that appears on a page is either computed in the browser by the model or rendered by the build from the model. If you find yourself typing one, add a data-build key instead.
  2. A parameter lives in model/config.js with its note. Nothing else hardcodes it.
  3. After changing the model, config, stories, funnel, or sources: npm run build && npm test.
  4. The build is deterministic: ages and lien seasoning in rendered fragments are measured from CONFIG.as_of, not the clock. The live calculator uses the visitor's real date.