Lot Line Analyzer - Personal or Commercial

1// Lot Line Analyzer - Personal or Commercial — real estate analysis module
2//
3// Underwriting as queued work. Each stage is a task, so a batch of files
4// retries independently and survives a restart:
5//
6//   realestate.analyse    a deal file -> year-one metrics, written as JSON
7//   realestate.project    a deal file -> N-year pro forma, IRR, equity build
8//   realestate.comps      a comparable-sales file -> a valuation range
9//   realestate.portfolio  a portfolio file -> a roll-up with aggregate DSCR/IRR
10//
11// Every handler reads a file the buyer wrote and writes a result into the
12// agent's data directory. Nothing here invents a rate, a rent, a growth
13// assumption or a comparable sale — a field that is missing is an error that
14// names the field, because a defaulted vacancy rate is someone else's money.
15//
16// The deal file, in full. Every `*_pct` is percentage points:
17//
18//   {
19//     "name": "412 Wheeler Ave",
20//     "purchase_price": 425000, "closing_costs": 9350, "rehab": 12000,
21//     "financing": { "down_payment_pct": 25, "annual_rate_pct": 6.875,
22//                    "term_years": 30, "extra_monthly_principal": 0 },
23//     "income":    { "monthly_rent": 3150, "other_monthly_income": 85 },
24//     "vacancy_pct": 6,
25//     "expenses": {
26//       "annual":         { "taxes": 5940, "insurance": 1725, "utilities": 840 },
27//       "percent_of_egi": { "management": 8, "maintenance": 5, "capex": 5 }
28//     },
29//     "growth": { "rent_pct": 3, "expense_pct": 2.5,
30//                 "appreciation_pct": 3, "selling_cost_pct": 6 }
31//   }
32//
33// Tuning lives in config/agent.json so a buyer changes policy without a
34// compiler:
35//
36//   "module": {
37//     "projection_years": 5,
38//     "dscr_floor": 1.20,
39//     "comps": { "max_distance_mi": 1.0, "max_sale_age_days": 365, "min_comps": 3 },
40//     "portfolio_path": "deals/portfolio.json",
41//     "portfolio_interval_s": 0
42//   }
43 
44#include <algorithm>
45#include <cctype>
46#include <string>
47#include <vector>
48 
49#include "bs9/agent.hpp"
50#include "bs9/json.hpp"
51#include "bs9/log.hpp"
52#include "bs9/metrics.hpp"
53#include "bs9/scheduler.hpp"
54 
55#include "underwriting.hpp"
56 
57namespace re = realestate;
58 
59namespace {
60 
61constexpr const char* kAnalyse = "realestate.analyse";
62constexpr const char* kProject = "realestate.project";
63constexpr const char* kComps = "realestate.comps";
64constexpr const char* kPortfolio = "realestate.portfolio";
65 
66/// A file name that cannot collide and cannot escape the data directory.
67std::string slug(const std::string& text) {
68  std::string out;
69  for (char c : text) {
70    const unsigned char u = static_cast<unsigned char>(c);
71    if (std::isalnum(u) != 0) {
72      out.push_back(static_cast<char>(std::tolower(u)));
73    } else if (!out.empty() && out.back() != '-') {
74      out.push_back('-');
75    }
76  }
77  while (!out.empty() && out.back() == '-') out.pop_back();
78  if (out.empty()) out = "result";
79  if (out.size() > 60) out.resize(60);
80  return out;
81}
82 
83/// The one thing that is genuinely transient here is a file that has not
84/// landed yet. Malformed input will read identically on the next attempt.
85bool looks_transient(const std::string& error) {
86  return error.rfind("cannot read", 0) == 0 ||
87         error.find(": cannot read") != std::string::npos;
88}
89 
90}  // namespace
91 
92namespace bs9 {
93 
94const char* module_name() { return "real-estate-analyzer"; }
95 
96void register_module(Agent& agent) {
97  const realestate::Settings settings =
98      realestate::Settings::from(agent.module_config());
99 
100  // -------------------------------------------------------------- analyse