Plan: JDM Ruleset Schema Rewrite

Every integration test guards on canopy_test_lib::infrastructure_available() (existing convention).

Every assertion uses assert_eq! / matches! against specific expected values. No assert!(…​ .is_some()), no unwrap_or(false).

Tests that exercise sad paths assert on the exact denial reason string the ruleset emits.

Tests for happy paths assert on the exact status: "approved", the benefit amount range, and the basis pathway.

Decision-table cells: bare ZEN expressions evaluated against the input. Example: ⇐ max_income, > 0, == "ssi_recipient", null, empty string "" (always-true wildcard).

Output cells: ZEN expressions producing the value to write to the named output field. String literals are double-quoted: "income_over_100_pct_fpl". Booleans: true/false. References to input fields by name: gross_income.

Expression nodes: {id, key, value} where key is the output field name and value is the ZEN expression. References to prior expressions in the same node use $.<key>.

Switch node statements: {id, condition} where condition is a ZEN boolean expression.

All ids must be unique within the file but otherwise are arbitrary strings.

Boolean: and, or, not

Comparison: ==, !=, <, ⇐, >, >=

Conditional: if cond then a else b

Arithmetic: +, -, *, /, %

Built-ins: round(x, 2), max(a, b), min(a, b), sum(arr), string(x) (cast)

Null: bare null

Self-reference inside an expressionNode: $.<key>

Step 1 must land before any later step (everything depends on the xtask rules check gate and the federal scan).

Step 2 must land before Step 4 and Step 5 (the TANF/Medicaid rewrites depend on the consolidated rules client; otherwise the ruleset_name typo silently breaks them).

Step 7 (CI enforcement) must land last so the gate only goes live once every file compiles.

Steps 3, 4, 5, 6 are otherwise independent.

xtask/Cargo.toml — add zen-engine = { workspace = true }

xtask/src/cmd/rules.rs — NEW

xtask/src/cmd/mod.rs — pub mod rules;

xtask/src/main.rs — register Rules { Check } subcommand

xtask/src/cmd/validate.rs — call rules::check() after cargo fmt --check and before cargo clippy (Step 7 makes this enforcing; Step 1 only adds the call)

services/canopy-rules/src/main.rs — add federal scan before the jurisdiction scan

services/canopy-rules/tests/rules_test.rs — add every_real_ruleset_compiles test

services/canopy-tanf/src/rules_client.rs — replace the bespoke TanfRulesClient with a thin wrapper around canopy_rules_client::RulesClient. Keep the TanfEligibilityInput/TanfEligibilityOutput/TanfBenefitInput/TanfBenefitOutput/WorkRequirementsInput/WorkRequirementsOutput types and the three high-level methods (evaluate_eligibility, calculate_benefit, evaluate_work_requirements); delete the inline HTTP client and the typo’d body construction. The high-level methods now call inner.evaluate(rule_set_name, "tanf", uuid, input_value) and serde-deserialize the output into the typed struct.

services/canopy-medicaid/src/rules_client.rs — same treatment for MedicaidRulesClient. Keep the MagiInput/NonMagiInput/ChipInput/HierarchyInput and corresponding output types; delete the inline HTTP client; route through canopy_rules_client::RulesClient.

services/canopy-tanf/Cargo.toml and services/canopy-medicaid/Cargo.toml — add canopy-rules-client = { workspace = true } if not already present.

services/canopy-tanf/src/main.rs and services/canopy-medicaid/src/main.rs — update the rules client construction to instantiate the new wrapper around canopy_rules_client::RulesClient::new(rules_url).

services/canopy-tanf/src/api/handlers.rs and services/canopy-medicaid/src/api/handlers.rs — confirm each handler that calls a rules method first calls rules.set_token(bearer_token).await so the caller’s JWT is forwarded. The shared client already supports this; the bespoke clients did too — verify the handler call sites still work after the swap.

services/canopy-tanf/tests/rules_client_smoke_test.rs (NEW) — POST against the running canopy-tanf service for a determination, assert it does NOT 400 with "missing field rule_set_name`". Will still 500 until the JDM rewrites land in Step 4; mark with `#[ignore] and a comment "unignore after Step 4 lands".

Same kind of NEW smoke test for canopy-medicaid, unignored after Step 5 lands.

rulesets/georgia/snap-eligibility.json — full rewrite

rulesets/georgia/snap-benefit-calculation.json — minimal valid stub

rulesets/federal/snap-alien-eligibility.json — full rewrite + change name field to georgia-snap-alien-eligibility to match the existing call site

services/canopy-snap/src/alien_eligibility.rs — remove the unwrap_or(false) / unwrap_or("no reason provided") / unwrap_or("7 CFR 273.4") masks at lines 100-115; replace with ok_or_else(|| ApiError::internal("missing eligible field", anyhow::anyhow!("output schema mismatch")))?

services/canopy-snap/src/alien_eligibility.rs — update doc comment at lines 80-81: remove the unimplemented "falling back to federal-…​" promise; replace with "Loaded from rulesets/federal/snap-alien-eligibility.json with name georgia-snap-alien-eligibility (see Plan: JDM Ruleset Schema Rewrite)."

services/canopy-snap/tests/snap_test.rs — remove the "broken JDM ruleset" skip in post_determine_returns_determination; strengthen its assertions; add 3 new strong-assertion tests

services/canopy-snap/tests/alien_eligibility_test.rs — NEW

inputs: [{id:"gi-income", type:"expression", field:"gross_monthly_income"}]

outputs: [{id:"gi-pass", type:"expression", field:"gross_income_test_passed"}, {id:"gi-basis", type:"expression", field:"gross_income_test_basis"}]

rules:

inputs: [{id:"at-bypass", type:"expression", field:"asset_test_passed"}, {id:"at-assets", type:"expression", field:"countable_assets"}]

outputs: [{id:"at-pass", type:"expression", field:"asset_test_passed"}, {id:"at-basis", type:"expression", field:"asset_test_basis"}]

rules: bypass row (if upstream already set the flag), pass row (⇐ asset_limit), fail row (> asset_limit).

post_determine_returns_determination — strengthen the existing test (no longer skipped). Household with household_size: 3, gross_monthly_income: 1200, countable_assets: 1500, no elderly/disabled. Expected: assert_eq!(data["status"], "approved"), assert_eq!(data["eligible"], true), data["benefit_amount"] parseable as Decimal in range [1, max_allotment], data["benefit_unit"] == "monthly", data["basis"] == "snap_eligible", and all *_test_passed/*_test_basis fields set.

post_determine_categorical_eligibility_bypasses_tests (NEW) — is_categorically_eligible: true, expect data["asset_test_basis"] == "categorical_standard_bypass".

post_determine_over_gross_income_denies (NEW) — gross_monthly_income: 9999, expect assert_eq!(data["status"], "denied"), data["gross_income_test_passed"] == false, data["gross_income_test_basis"] == "gross_income_fail", benefit_amount parses as Decimal 0.

post_determine_minimum_benefit_path (NEW) — household_size: 1, low income. Call GET /v1/params?household_size=1 first to read minimum_benefit; assert data["benefit_amount"] equals that value. Do not hardcode the dollar amount.

tests/alien_eligibility_test.rs (NEW) — POST against the alien eligibility internal endpoint; assert all 3 output fields for the refugee, LPR-5-year, and unqualified-alien cases.

rulesets/georgia/tanf-eligibility.json — full rewrite

rulesets/georgia/tanf-benefit-calculation.json — full rewrite

rulesets/georgia/tanf-work-requirements.json — full rewrite

services/canopy-tanf/tests/tanf_test.rs — remove the "broken JDM ruleset" skip; strengthen post_determine_returns_determination; add 4 new strong-assertion tests

post_determine_returns_determination — strengthen. household_size=3, dependent_children=2, deprivation_type="CSO", deprivation_verified=true. Expect status: "approved", eligible: true, non-empty signature, benefit_amount > 0.

post_determine_no_dependent_children_denies (NEW) — dependent_children: 0. Expect status: "denied", denial_reasons[0] contains "No dependent children".

post_determine_time_limit_exceeded_denies (NEW) — pre-create a time limit record with months_used: 60 via the canopy-tanf store helper, then POST. Expect denial_reasons[0] contains "Time limit".

post_determine_no_deprivation_denies (NEW) — deprivation_type: null. Expect denial_reasons[0] contains "No qualifying deprivation".

post_work_requirements_caretaker_exempt (NEW) — POST work-requirements internal endpoint with youngest_child_age_months: 6. Expect exempt: true, exemption_reason contains "infant".

rulesets/georgia/medicaid-magi.json — full rewrite encoding evaluate_magi_coa logic from services/canopy-medicaid/src/determine.rs:280-352

rulesets/georgia/medicaid-non-magi.json — full rewrite encoding evaluate_non_magi_coa from lines 383-419

rulesets/georgia/chip-eligibility.json — full rewrite encoding evaluate_chip_coa from lines 356-380

rulesets/georgia/medicaid-eligibility-hierarchy.json — full rewrite encoding the EE15 hierarchy logic

services/canopy-medicaid/src/determine.rs:

services/canopy-medicaid/src/rules_client.rs — extend the input types with threshold fields the rulesets need (pregnant_women_threshold_cents, child_0_1_threshold_cents, parent_caretaker_threshold_cents, pathways_threshold_cents, chip_lower_threshold_cents, chip_upper_threshold_cents)

services/canopy-medicaid/src/api/handlers.rs — extract bearer token from incoming request and call rules.set_token(token).await before the determine call (mirror canopy-tanf pattern)

services/canopy-medicaid/tests/medicaid_test.rs — add 8+ integration tests covering each COA boundary

magi_parent_caretaker_eligible_at_30_pct_fpl — expect assigned_coa == "parent_caretaker", status == "approved"

magi_parent_caretaker_denied_at_36_pct_fpl — expect denial_reasons contains "income_over_35_pct_fpl"

magi_children_under_19_age_5_eligible — expect assigned_coa == "children_under_19"

magi_children_age_19_ineligible — expect denial_reasons contains "age_19_or_older"

magi_pregnant_women_at_220_pct_eligible — expect assigned_coa == "pregnant_women"

chip_age_18_at_200_pct_eligible — expect assigned_coa == "peachcare"

chip_age_18_at_248_pct_denied — expect denial_reasons contains "income_over_247_pct_fpl"

non_magi_ssi_recipient_eligible — expect assigned_coa == "ssi_medicaid"

hierarchy_picks_most_advantageous — applicant eligible for both parent_caretaker and PeachCare; expect assigned_coa == "parent_caretaker"

rulesets/georgia/caps-eligibility.json — minimal valid zen 0.55 stub

rulesets/georgia/wic-eligibility.json — same

xtask/src/cmd/validate.rs — already calls rules::check() from Step 1; confirm it bails on failure (this step makes the gate enforcing now that every file compiles)

.gitlab-ci.yml — add a rules-check job at the lint/check stage that runs cargo xtask rules check. Fast (< 30s, no devstack required).

Audit and remove any remaining if resp.status == 500 { eprintln!(…​); return; } patterns in services/canopy-snap/tests/snap_test.rs, services/canopy-tanf/tests/tanf_test.rs, services/canopy-security/tests/security_test.rs, services/canopy-reporting/tests/reporting_test.rs.

NamedFilesystemLoader in services/canopy-rules/src/engine.rs — custom DecisionLoader impl that maps logical ruleset names (the name field inside each JDM file) to on-disk paths. Scans rulesets/federal/ then rulesets/{jurisdiction}/ at startup, skips non-JDM parameter files by checking for a top-level nodes array.

Wrapped in zen-engine’s CachedLoader for memoization per the SDK doc’s keep_in_memory: true equivalent.

LocalPoolHandle::new(1) from tokio-util for pinned !Send evaluation futures. The pinned closure serializes the zen response to plain JSON before returning so only Send types cross the thread boundary.

?trace=true query parameter on POST /v1/evaluate. Response shape is now {output, duration_ms, trace?}. Verified against the SNAP ruleset during Step 3 debugging — invaluable for inspecting broken expression cells.

Error handling matches directly on EvaluationError::LoaderError(LoaderError::NotFound(_)) instead of string-matching the outer Display (which only produces "Loader error" and hides the inner variant).

Drops POST/PUT/DELETE /v1/rule-sets. Rulesets are filesystem-backed per ADR-003 — there is no runtime mutation path. GET /v1/rule-sets (list) and the new GET /v1/rule-sets/{name} (read by logical name) are retained.

Drops the rule_sets DB table via migration 20260412000000_drop_rule_sets_table.sql. It was a pre-loader cache that was never authoritative after the auto-import landed. The rule_evaluations audit table stays.

Drops ~780 lines of bespoke code (net -286 after the refactor adds).

10/10 canopy-rules tests pass against devstack, including the strengthened every_real_ruleset_compiles runtime gate which exercises all 12 on-disk JDM files via the real loader path.

Eight tests that depended on POST /v1/rule-sets creation were deleted. New tests cover the filesystem-backed listing, get-by-name, trace, and not-found paths.

rulesets/georgia/snap-eligibility.json — full rewrite per the schema delta table in the Context section. Three concrete zen 0.55-specific fixes beyond the schema delta were discovered during debugging and documented here for the TANF / Medicaid / CHIP rewrites in Steps 4-5:

rulesets/georgia/snap-benefit-calculation.json — rewritten as a minimal 2-node stub since no service calls it and the real benefit math lives in expr-benefit inside georgia-snap-eligibility.

rulesets/federal/snap-alien-eligibility.json — name field renamed from federal-snap-alien-eligibility to georgia-snap-alien-eligibility (option (a) decision from the Step 3 table). The file’s content was already correct zen 0.55 schema.

Latent graph bug fixed. The original expr-standard-ce → expr-benefit edge skipped expr-deductions, leaving net_income undefined when expr-benefit computed round(net_income * 0.30, 2). Fixed by routing expr-standard-ce → expr-deductions → dt-net-income (bypass row) → expr-benefit so net_income is always computed. This was never caught before because no test had ever reached expr-benefit in the standard-CE arm.

Decimal → JSON number conversion. rust_decimal::Decimal serializes as a JSON string by default, which would make ZEN expressions like 0.20 * gross_earned_income fail on type mismatch. services/canopy-snap/src/determine.rs now converts every Decimal in rules_input to a bare JSON number via to_f64. f64’s 52-bit mantissa exactly represents any SNAP dollar amount under $1B, which is adequate precision. The same conversion pattern must be applied in Step 4 (canopy-tanf determine handler) and Step 5 (canopy-medicaid determine handler).

?trace=true unblocked the debugging loop. Landing the trace support in Step 2.5 turned a multi-hour guess-and-check cycle on the ZEN expression syntax into a minutes-long iteration. Every subsequent JDM rewrite should lean on cargo xtask rules check for static schema validation AND curl -X POST /v1/evaluate?trace=true against the live service for runtime trace.

unwrap_or masks removed. services/canopy-snap/src/alien_eligibility.rs previously used unwrap_or(false), unwrap_or("no reason provided"), and unwrap_or("7 CFR 273.4") to mask output schema mismatches. Replaced with hard ok_or_else(|| ApiError::internal(…​)) returns. Any future ruleset output drift now surfaces as a clean 500 instead of a silent wrong result.

Another latent bug fixed. The original tanf-eligibility.json had an r-no-children rule with all-empty conditions that always matched as a fallback AND output eligible: true — so a household with 0 dependent children would have been approved. The rewrite fixes this: c-children: "⇐ 0" → deny with "No dependent children" in the denial reasons. Documented in post_determine_no_dependent_children_denies.

TanfBenefitInput field rename. The old state_max_benefit: Decimal and payment_standard: Decimal fields were always passed as Decimal::ZERO by determine.rs with the comment "loaded by rules engine from jurisdiction config" — except the rules engine has no way to read jurisdiction config, so the whole benefit math was a no-op stub. Replaced with effective_date: NaiveDate and expiration_date: NaiveDate, which determine.rs now computes (today → +6 months) and the ruleset passThrough`s to its output unchanged. The ruleset’s new `family_maximum ternary is the actual math per PAMMS 1810.

Decimal serialization asymmetry discovered and worked around. rust_decimal::Decimal’s default serde impl (under the workspace’s `serde-str feature) deserializes from strings and serializes as strings. But ZEN arithmetic needs numbers on input, and the JDM emits numbers on output. Fix: local serialize_decimal_as_number helper for TanfBenefitInput.countable_income and every TanfEligibilityInput Decimal field (converts via to_f64); local deserialize_decimal_from_number for TanfBenefitOutput.benefit_amount (accepts JSON numbers OR strings). Same pattern will be needed in Step 5 for MagiInput / NonMagiInput / ChipInput / HierarchyInput on canopy-medicaid.

PAMMS 1810 family-max table hardcoded in the ruleset. The family maximum by household size is currently embedded as a ternary cascade inside tanf-benefit-calculation.json:

household_size <= 1 ? 235 : (household_size == 2 ? 280 : (household_size == 3 ? 330 : ...))

Real TANF benefit math (boarder exclusion, earned-income disregard, child-support gap budgeting per PAMMS 1605/1645) is out of scope. The Step 4 rewrite implements the minimum viable math to produce a positive benefit for approved cases. Full PAMMS 1605/1645 alignment is tracked by the existing tanf-pamms-alignment plan and should compose cleanly with this rewrite — add new expression nodes before expr-benefit that compute countable_income from raw income + deductions.

canopy-tanf does not expose a work-requirements evaluation endpoint. The new work_requirements_caretaker_of_infant_is_exempt integration test POSTs directly to canopy-rules /v1/evaluate against the tanf-work-requirements ruleset, mirroring the Step 3 alien-eligibility test pattern. A follow-up should add a POST /v1/work-requirements/evaluate handler to canopy-tanf that wraps the rules client call — similar to how canopy-snap’s post_determine wraps its own rules evaluation.

Step 2 smoke test deleted. services/canopy-tanf/tests/rules_client_smoke_test.rs was added in Step 2 as a stopgap check that the consolidated rules client didn’t 400 on the rule_set_name typo. Now that the full determine path works end-to-end with strong assertions, the smoke test is redundant. The equivalent canopy-medicaid smoke test stays in place until Step 5 lands.

TanfParameterTable extended to load [tanf.earned_income].disregard_amount_cents (PAMMS 1615 flat $250 disregard per employed individual). #[allow(dead_code)] removed from gross_income_ceiling and standard_of_need — both are now used.

determine.rs computes real net income. Previously let net_income = gross_income; (the comment said "deductions applied by rules engine" but the rules engine had nothing to deduct with). Now: split income per-person by earned type (wages / self_employment / self_employment_net), sum each earner’s gross earned, apply min(earner_gross, flat_disregard) per PAMMS 1615, subtract the total from gross income, clamp to zero.

TanfEligibilityInput extended with gross_income_ceiling and standard_of_need fields injected from the parameter table per ADR-011 — never hardcoded in the ruleset.

tanf-eligibility.json now tests income. Two new rules: r-gross-over compares gross_income > gross_income_ceiling → denies with PAMMS 1501 gross ceiling reason; r-net-over compares net_income > standard_of_need → denies with PAMMS 1501 SON reason. Both rules set the corresponding *_pass output field to false so downstream consumers can surface which gate failed.

Decimal serde helpers moved to shared crate. canopy-rules-client::decimal_serde (NEW) owns serialize_as_number / deserialize_from_number / serialize_opt_as_number with 8 unit tests. canopy-tanf’s local serialize_decimal_as_number / deserialize_decimal_from_number functions deleted. Step 5 (canopy-medicaid) will consume these shared helpers too — avoids triplicating the same workaround for `rust_decimal’s serde-str asymmetry.

Inline Rust evaluators deleted. evaluate_magi_coa, evaluate_chip_coa, evaluate_non_magi_coa (plus load_thresholds_from_jurisdiction and MedicaidThresholds) removed from determine.rs. The ~20 unit tests exercising those functions are replaced by 7 HTTP integration tests that verify the full canopy-medicaid → canopy-rules → JDM evaluation → response path.

MedicaidParameterTable (NEW). Mirrors the TanfParameterTable pattern: loads rulesets/federal/fpl-2026.json (HH-indexed monthly FPL) + rulesets/{jurisdiction}/jurisdiction.toml [medicaid] (percentage thresholds) once at startup. Injected via Extension<Arc<MedicaidParameterTable>>. Replaces the per-request load_thresholds_from_jurisdiction that did filesystem I/O with silent fallback defaults.

Hierarchy ruleset uses parenthesized ternaries. The medicaid-eligibility-hierarchy.json expression node first computes 12 some(eligible_coas, # == "coa_code") booleans, then walks the PAMMS 2052 priority order via a deeply-nested ternary chain with explicit parenthesization. An initial version had unbalanced parentheses (11 open, 12 close) which produced a generic "Failed to evaluate expression" error at runtime — zen-engine’s error message does not surface the parse error details. Root-caused and fixed by counting parens; added hierarchy_jdm_evaluates_in_process unit test that evaluates the JDM in-process to catch this class of error in CI.

Parallel rules evaluation via tokio::try_join!. determine.rs fires evaluate_magi, evaluate_non_magi, and evaluate_chip concurrently since they’re independent HTTP calls. Then joins results and maps per-COA booleans onto the CMD cascade.

Former foster care COA stubbed. The MAGI ruleset outputs former_foster_care_eligible: false (same as the deleted inline Rust). Foster care verification lives outside the ruleset; the full implementation is tracked by medicaid-implementation.adoc.

Non-MAGI ABD COAs largely stubbed. SSI auto-qualify works; QMB/SLMB/QI-1/AMN return false with stub denial reasons matching the deleted inline Rust. Full ABD expansion tracked by medicaid-implementation.adoc.

Token forwarding race condition (pre-existing, all 3 services). RulesClient::set_token() mutated shared Arc<RwLock<Option<String>>> state. Under concurrent requests, token B could overwrite token A before A’s evaluate calls fired — wrong audit identity. Fix: evaluate() now takes token: Option<&str> per-call; set_token() deleted; tokio dep dropped from canopy-rules-client.

Missing TANF income denial test coverage. The r-gross-over and r-net-over rules added in Step 4 had zero integration test coverage. Added post_determine_gross_income_over_ceiling_denies and post_determine_net_income_over_son_denies.

Misnamed Medicaid test. post_determine_adult_denied_when_not_parent_caretaker actually asserted Pathways approval. Renamed to post_determine_adult_under_100_pct_fpl_gets_pathways.

Unnecessary hierarchy HTTP call on full denial. When eligible_codes is empty, the hierarchy ruleset call was a no-op round-trip. Added short-circuit: if eligible_codes.is_empty() { return denied }.

Redundant cargo build -p xtask in CI. cargo xtask rules check already triggers the build implicitly. Removed the extra line.