Repository navigation
How the Rules Engine Works
This page explains how OpenBridge turns a household's answers into a result for each program. It is for contributors who will read or change the engine code or the rule data. The engine is the riskiest part of the project: a wrong answer here can cost a family food or health coverage.
The source of truth is the code in
packages/eligibility-engine/src and the
standard in .kiro/steering/eligibility-rules.md.
This page is a map, not a copy.
Everything starts in evaluateEligibility() in
engine.ts. It takes four inputs
and returns one result per program:
- the household profile (who lives there, income, costs, flags such as
receivesSnap); - the state adapter (the state's rule values, see State adapters);
- the federal data (poverty line tables and SNAP values from
data/federal/); - the evaluation date, as a
YYYY-MM-DDstring.
Then it runs these steps:
-
Normalize.
normalizeProfile()works out the total gross monthly income from every income source, picks the poverty-line region from the state code (contiguous,alaska, orhawaii), and assumes the person lives in the state unless told otherwise. -
Pick the programs. By default:
snap,medicaid,wic,liheap,tanf. A program with no evaluator, or one the adapter does not configure, returnsunknownwith the reasonPROGRAM_NOT_YET_SUPPORTED. It is never left out. -
Run each evaluator on its own. Each program has one file in
programs/. Evaluators never read each other's output. "Already gets SNAP" style shortcuts come only from what the person says they already receive. -
Work out the household and poverty line per program. Programs count a household
differently.
household.tsbuilds the SNAP household and each person's Medicaid (MAGI) household. A pregnant person counts as 1 plus the expected number of babies for Medicaid and WIC, but not for SNAP. The poverty line (FPL) is the base for one person plus a fixed amount per extra person (fpl.ts). -
Downgrade for missing input. If the household has no members or no state, or an hourly job
has no hours per week, results become
possibly_eligiblewithMISSING_REQUIRED_INPUT. -
Flag stale data. If the evaluation date is past the FPL or SNAP
expectedRefreshDate, or the adapter'slastVerifiedis more than 365 days old, every result getsDATA_MAY_BE_OUT_OF_DATEfirst. See Yearly data updates.
Medicaid, CHIP, and WIC return a result for each person plus a rollup equal to the most
encouraging person's result (mostEncouraging()). SNAP, LIHEAP, and TANF return one result for the
household.
Every evaluator decides through decideOutcome() in
outcome.ts. Nobody hand-rolls an
outcome. The checks run in this order, and the first match wins:
| Order | Condition | Outcome |
|---|---|---|
| 1 | A required input is missing, a factor cannot be computed, or within 10% of a limit | possibly_eligible |
| 2 | A hard disqualifier applies and no pathway remains | ineligible |
| 3 | Passes every hard test, but relies on what the person told us | likely_eligible |
| 4 | Passes every hard test with verified inputs | eligible |
| 5 | Anything else | unknown |
The 10% margin is NEAR_THRESHOLD_MARGIN_PCT. Each evaluator decides when it applies: Medicaid
and LIHEAP flag income within 10% on either side of the limit, while SNAP flags it only when income
is just over a limit. Because uncertainty is checked before a hard "no",
a person close to a limit is never told they do not qualify. Immigration status alone never leads
to ineligible. Changing this ladder needs maintainer approval and an ADR (see
AGENTS.md section 5).
The engine never writes English. It returns codes, and the web app turns them into words.
-
Reason codes (
{ code, params }) explain each result. Keys live inreason-codes.ts. Params are raw values such as cents or counts, never formatted text. Every key needs an English string inreasons.json;npm run check:reason-keysenforces this. - Factor rows show each test: a label code, the value, the limit, and pass or fail.
-
Calculation steps are the "Show the math" trace. Each step has a label code from
calculation-steps.ts, a value, a unit (cents,pct, orcount), and an operation (input,rule,limit,subtract,result). Arulestep points at thesources[]field it came from, so the app can link the official source or say "Source not listed yet". The trace holds the exact numbers the evaluator compared, so it cannot drift from the decision.
The engine has no network, no storage, no DOM, no i18n, no clock reads, and no randomness. The date and all rule data are passed in. That gives three things:
- Same input, same output. Golden test cases can pin exact answers forever. See Golden test cases.
- Privacy. Code that cannot do I/O cannot leak a household's details.
- Reuse. The same engine runs in the browser, in the single-file offline download, and in the MCP server.
A made-up household in Washington: one adult, age 30, earning $1,000 a month in wages, checked on 2024-06-01 with the current draft adapter and the 2024 federal data.
SNAP (Washington uses broad-based categorical eligibility, so only the gross test applies):
- Household size: 1. Annual FPL: $15,060, so monthly FPL is $1,255.00.
- Gross limit: 200% of FPL, from
snap.grossIncomeLimitPct. That is $2,510.00 a month. - $1,000 is under $2,510, so the gross test passes. The net income and asset tests are waived.
- Income is self-reported, so the ladder gives
likely_eligible. - Benefit estimate: earned income deduction 20% ($200) and standard deduction ($198) leave net
income of $602. 30% of that is $180.60. The maximum allotment for one person is $291, so the
estimate is $291.00 minus $180.60, which is $110.40 (
estimatedBenefitCents: 11040).
Reasons returned: SNAP_ESTIMATED_BENEFIT, GROSS_INCOME_WITHIN_LIMIT, and
SNAP_ABAWD_TIME_LIMIT_MAY_APPLY (an adult with no children and no employment status given; it is
a notice, never a "no"). Under broad-based categorical eligibility the trace shows the gross test
and the benefit steps, not the net-income breakdown.
Medicaid for the same person: annual income of $12,000 is about 80% of FPL, under the 138% adult
limit, so the result is likely_eligible.
These numbers were checked by running the engine with these inputs. To pin them in a test, write a
fixture with "expectedBenefits": { "snap": 11040 }. The engine's own tests run with:
npm test -w @openbridge/eligibility-engineOpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers