# WP18 — baseline configuration (Part B model, research/model_specification.md §B).
# Every parameter: value, unit, and provenance. "illustrative" = no verified Canadian/Québec
# source in research/literature_matrix.csv; "normalisation" = fixed by construction;
# "verified target" = a moment reported in a verified source (see calibration.py), used as a
# comparison, never as a fitted claim. Annual values are converted to the 5-year model period
# in src/model.py (conversion formulas recorded there and in results/data/parameters.csv).
#
# One model period = 5 years. Units of value: the average 5-year labour income of a working-age
# household at the median productivity state (E[z] = 1, mean age profile = 1) = 1.

meta:
  name: baseline
  seed: 20261020               # numpy Generator seed for the dynasty panel (common random numbers)
  period_years: 5

demographics:
  J: 12                        # ages 1..12 = 25-29 .. 80-84 (spec B.1)
  j_retire: 9                  # first retirement age index (65-69)
  j_gift: 7                    # parent gives the inter-vivos transfer; child enters at age 1
  j_estate: 7                  # child receives the parent's estate (J - j_gift + 2 = 7)

preferences:
  beta_annual: 0.96            # illustrative (standard lifecycle value); per period = 0.96^5
  gamma: 2.0                   # CRRA curvature on the composite c^(1-alpha) s^alpha; illustrative
  alpha: 0.20                  # housing-services share in the composite; illustrative (Statistics
                               # Canada shelter share of spending is ~0.3 incl. utilities; we use
                               # the lower value because owner services are gross of maintenance)
  chi: 0.0                     # ownership utility premium (s = (1+chi) h); baseline 0 (spec B.2)
  nu: 2.0                      # warm-glow weight (De Nardi 2004 form); illustrative, chosen so that mean gifts ~ 2 years of income
  x_shift: 1.0                 # luxury shift of the warm glow (transfers are a luxury); illustrative (see calibration.py)

income:
  rho_annual: 0.95             # annual AR(1) persistence of log productivity; illustrative (standard)
  sigma_annual: 0.15           # annual innovation s.d.; illustrative (standard)
  n_z: 5                       # Rouwenhorst states
  # 5-year conversion (model.py): rho5 = rho^5; the unconditional variance of log z is kept equal
  # to the annual one, sigma5 = sqrt(var_u * (1 - rho5^2)), var_u = sigma^2/(1 - rho^2).
  age_profile: [0.70, 0.88, 1.02, 1.10, 1.15, 1.13, 1.06, 0.96]   # ages 1..8 (25-64), mean = 1; illustrative hump
  replacement_rate: 0.50       # pension = rr * ybar_8 * z_last; illustrative
  rho_intergenerational: 0.0   # correlation of child z_1 with parent z at j_gift; 0 = equal-income design
  sigma_transitory: 0.03       # s.d. of a transitory, unanticipated i.i.d. income component per period (log), realised
                               # before decisions; spreads the atoms of the cash distribution (zero-gift entrants,
                               # hand-to-mouth renters) that otherwise make excess demand discontinuous; illustrative
  dep_premium_annual: 0.0      # excess annual real return on household deposits ("renter investment return"); 0 baseline

housing:
  h_sizes: [1.0, 1.5, 2.25, 3.4]   # owner-occupied sizes, units of housing (spec B.12)
  s_min: 0.30                  # minimum rented size; illustrative (< h_min)
  s_max: 3.4                   # maximum rented size = largest house
  m_annual: 0.01               # maintenance, share of value per year; illustrative (per period = 5x)
  kappa_b: 0.025               # buying cost, share of price; illustrative (Québec transfer duty + legal)
  kappa_s: 0.05                # selling cost, share of price; illustrative (brokerage)
  kappa_f: 0.01                # refinancing cost, share of house value; illustrative
  delta_H_annual: 0.01         # physical depreciation of the stocks per year; illustrative

mortgage:
  N: 5                         # amortisation, periods (25 years); Canadian standard (literature_review §7)
  theta: 0.20                  # minimum down payment (max LTV 0.80); Canadian uninsured threshold; illustrative baseline
  psi: 0.39                    # payment-to-income cap at the qualifying rate; illustrative (GDS-type cap)
  stress_annual: 0.02          # qualifying-rate add-on, annual (stress test); illustrative
  contract: frm                # frm | term5 | arm — identical in the stationary equilibrium (spec B.5)
  spread_annual: 0.0           # mortgage spread over the deposit nominal rate; baseline 0

rates:
  r_annual: 0.02               # real rate per year; illustrative (small open economy, exogenous)
  pi_annual: 0.02              # steady-state CPI inflation per year; Bank of Canada 2% target (institutional)

rental:
  phi: 0.05                    # landlord operating wedge per period (share of value); illustrative
  sigma_seg: 1.0               # segmentation (1 = fully segmented stocks, 0 = one stock); spec B.6
  eta_rent: 1.0                # rent indexation to a surprise (1 = full); baseline
  eta_wage: 1.0                # wage indexation to a surprise (1 = full); baseline

supply:
  eps: 1.0                     # long-run owner-occupied supply elasticity; ILLUSTRATIVE (no verified Canadian estimate; range 0.05-3)
  eps_r: 1.0                   # rental supply elasticity; illustrative
  H_bar: null                  # scale; null = set by normalisation p* = 1 (calibration.py)
  Hr_bar: null                 # scale; null = set by normalisation p^r* = 1
  p_ref: 1.0                   # price normalisation

government:
  tau_b: 0.0                   # transfer tax on gifts and estates, rebated lump-sum to age-1 households

grids:
  n_a: 50                      # liquid assets, double-exponential spacing
  a_max: 15.0                  # units of average 5-year income
  n_b: 20                      # real mortgage balance per unit of house: [0, (1-theta) p_cap]
  p_cap_factor: 1.6            # balance grid covers prices up to p_cap_factor * p_ref
  n_x: 120                     # cash-on-hand grid for the rent / buy / refinance branches
  x_max: 22.0
  n_B: 11                      # loan choices at origination, fractions of the LTV cap
  n_gift: 12                   # gift choices at j_gift, fractions of cash (0 .. gift_frac_max)
  gift_frac_max: 0.6
  K_estate: 5                  # points of the estate lottery
  c_min: 0.01                  # consumption floor (feasibility)

simulation:
  n_dynasties: 96000           # dynasty slots (16 000 per phase); cross-section = 2 x n_dynasties
  burn_periods: 60             # 10 generations from an arbitrary initial condition (stationary; convergence checked in tests)

equilibrium:
  tol_excess: 5.0e-4           # relative excess demand tolerance; MC noise in excess-demand differences is ~1e-3 for 0.5 % price moves, so the equilibrium price is pinned to about +/-0.05 %
  tol_lottery: 1.0e-3          # relative change of the estate lottery points
  max_outer: 10                # lottery / rebate fixed-point rounds
  damping: 0.7                 # damping of the lottery / rebate update

transition:
  T: 14                        # periods (70 years); residual at T reported
  tol: 1.5e-3                  # max relative excess demand along the path (single-period cross-sections of 192 000 households: noise floor ~1e-3)
  max_iter: 20
  jac_step: 0.01               # FD step in log price (averages the grid kinks)
  pi_surprise: 0.10            # unexpected cumulative CPI surprise in the shock period (10 % ~ 2 pp/yr over 5 yrs)