Module welfare 

Welfare economics primitives: social welfare functions, inequality and poverty metrics, cost-benefit analysis with distributional weights, and a needs/survival-floor allocation model.

Allocation class

All kernels here are AllocationClass::HotZeroHeap. Sorting scratch uses fixed-capacity stack arrays ([f64; MAX_POPULATION]) or caller-provided output buffers — never Vec, String, or Box. No allocation occurs on any path, hot or cold, within this module.

Rights-affecting use

Poverty metrics, distributional weights, and the survival-floor allocation model can inform decisions that affect entitlements, transfers, or access. Those uses MUST be paired with SHACL/deontic checks (see deontic_logic.rs opcodes OP_OBLIGATE/OP_FORBID/OP_PERMIT) and capacity-modalities review before any UI exposure or downstream action. The repr(C) report structs returned by rights-affecting functions carry diagnostics and assumptions, not just a scalar, so callers can audit the basis of a computed allocation. No function in this module performs or recommends an external action on its own.

Structs

WelfareReport

Report returned by rights-affecting welfare kernels.

Enums

WelfareError

Welfare kernel error vocabulary.

Constants

ASSUMPTION_DEGENERATE

Assumption flag: result is degenerate (e.g. zero-mean population for Gini).

ASSUMPTION_FLOOR_CLAMPED

Assumption flag: at least one observation was clamped to the survival floor.

ASSUMPTION_LINE_ABOVE_MAX

Assumption flag: poverty line is above the maximum observed income.

ASSUMPTION_WEIGHTED

Assumption flag: distributional weights were applied (CBA only).

MAX_POPULATION

Maximum population size supported by stack-array scratch buffers.

Functions

atkinson_inequality

Atkinson inequality index with inequality-aversion parameter epsilon > 0.

distributional_npv

Distributional NPV: NPV with per-period distributional weights.

gini_coefficient

Gini coefficient in [0, 1] via the mean-absolute-difference formula:

headcount_poverty

Headcount poverty: returns (count_poor, headcount_ratio) where count_poor is the number of observations strictly below poverty_line and headcount_ratio = count_poor / n.

lorenz_curve_into

Write the Lorenz curve as interleaved (cumulative_population_share, cumulative_income_share) pairs into out: [pop0, inc0, pop1, inc1, ...], sorted ascending by income. Returns the number of points written.

nash_welfare

Nash social welfare: the product of utilities, prod_i u_i.

net_present_value

Net present value: NPV = sum_{t=0}^{n_periods-1} (B_t - C_t) / (1+r)^t.

poverty_gap_ratio

Poverty gap ratio: sum(max(0, line - income)) / (n * line).

rawlsian_welfare

Rawlsian (minimax / maximin) social welfare: min_i u_i.

survival_floor_allocation_into

Allocate a fixed budget budget across needs so that each recipient first receives their survival floor floors[i], then the residual is distributed proportionally to surplus need needs[i] - floors[i].

utilitarian_welfare

Utilitarian (sum) social welfare: sum_i u_i.