T2-7 — Reported-change → dry-run materiality → recert nudge + change-of-circumstance notices (#680)

Port this plan to .adoc + nav entry (the (plan) commit).

Amend ADR-027 with a T2-7 as-built amendment: the event-subscriber trigger (Decision A); corpus replay (B); the complete frozen-policy bundle ©; the unsigned + write-free dry-run (D); the dry-run as_of (J); the pre-T2-7 backfill boundary.

Amend ADR-028: the snapshot’s corpus_hash + the enriched policy_params bundle are replay inputs (realizing the reproducibility the Decision already intended); canopy-rules gains corpus-version history.

Add [snap.materiality] benefit_delta_threshold_cents to rulesets/georgia/jurisdiction.toml + a citations.toml entry. The materiality dollar amount is a Canopy operational/product decision, not a federal figure — authority = "operational", and flagged for Georgia SME confirmation (#921). Do not cite 7 CFR 273.12(a)(5) (simplified-reporting), and do not conflate with the [snap.verification_thresholds] PAMMS-3035 $25 verification triggers.

Files: docs/…​/adrs/adr-027-.adoc, adr-028-.adoc, rulesets/georgia/{jurisdiction,citations}.toml, nav.adoc, the plan .adoc.

Deps: cargo add lru parking_lot (neither is a workspace dep yet).

Store: ruleset_corpus_versions migration; extend NamedFilesystemLoader::scan to retain the winning name→raw map; persist the current corpus idempotently in RulesEngine::new/bootstrap before the service reports ready (closes the startup race).

Replay loader + cache: InMemoryLoader (impl DecisionLoader over pre-parsed Arc<DecisionContent>); parking_lot::Mutex<lru::LruCache<CorpusHash, Arc<DecisionEngine>>> (cap ~8) — clone the Arc out and drop the guard before spawn_pinned (never hold a parking_lot guard across .await). Replay evals reuse the existing LocalPoolHandle.

Pin + ephemeral params on POST /v1/evaluate (EvaluateParams already carries trace; add corpus_hash + audit):

Load-bearing tests: replay-over-stored-bytes ≡ live output for the same input (proptest over a few corpora); a determination’s corpus_hash is replayable immediately after the boot that produced it (race closed); pinned eval returns the pinned hash; ?audit=false writes no audit/outbox row (assert counts); unknown corpus → 422; INSERT idempotent across restarts; cache eviction → rebuild identical.

Files: services/canopy-rules/src/{engine.rs,api/mod.rs,store.rs}, new migration, services/canopy-rules/Cargo.toml, crates/canopy-rules-client/src/lib.rs, crates/canopy-contracts-rules/src/rule_sets.rs, root Cargo.toml. (No new path → the == 4 OpenAPI count is unchanged.)

Snapshot enrichment: extend the snapshot capture so policy_params includes the full bundle (thresholds + pay_periods + SE settings). All new determinations carry it. As-built: policy_params serializes a typed SnapPolicyBundle (the 15 thresholds stay flat + identically named so the derivation-graph Param resolution is unchanged); PayPeriods was promoted into canopy-contracts-snap so it can ride the bundle, re-exported from the service. SnapParameters::policy_bundle() / ::from_policy_bundle() convert (the latter nulls certification/renewal months — a dry-run computes no dates).

Extract evaluate_verdict from determine.rs (the verdict-computation region: SE pre-processing → assemble rules_input → alien pre-check → main eval → parse). It begins after create_snap_application and ends before the DEK-mint/sign/persist tail; keep app-create + antecedent validation in determine() only. As-built: evaluate_verdict is a thin coordinator over build_rules_input + run_alien_precheck + run_eligibility_rulesets + parse_verdict (the decomposition keeps each fn under the B2 100-LOC budget; B2 stays 123, B3a 754 — the opaque-JDM-I/O serde_json::Value sites carry // STRUCTURAL-VALUE).

Endpoint POST /v1/determine/dry-run: body = DryRunDetermineRequest { context, policy_bundle, corpus_hash }; returns DryRunOutcome. Mints no DEK, seals nothing, signs nothing, persists nothing, emits nothing (and via audit=false, no rules-audit rows). As-built: no as_of on the snap-level request — the orchestrator (MR4, Decision J) reads facts as-of the change’s effective date and assembles the ApplicationContext, so snap’s verdict pipeline needs no date. RulesClient::evaluate_pinned now maps a pinned-corpus 422 to a typed UnprocessableEntity so the unknown-corpus case surfaces as 422 (CorpusUnavailable), not a 500 (the MR4 caller degrades to manual review).

Load-bearing tests: evaluate_verdict ≡ the full determine() (status, benefit_amount) for the same input (refactor guard, via the dry-run pinned to the determination’s own corpus + bundle); a dry-run leaves snap row counts unchanged (write-free; household-scoped, parallel-safe); the snapshot serializes the full bundle; unit round-trips for policy_bundle() / from_policy_bundle().

Files: services/canopy-snap/src/{determine.rs,se_deduction.rs,alien_eligibility.rs,api/determine_handler.rs,api/mod.rs,params.rs}, crates/canopy-contracts-snap/, crates/canopy-rules-client/src/lib.rs, crates/canopy-test-lib/src/clients/snap.rs. *OpenAPI count 22 → 23.

Endpoint POST /v1/eligibility/determine/dry-run: factor the household/context-assembly out of determine_inner; the dry-run path skips the eligibility_requests slot, signature verification, program_determinations/combined_results persistence, and the outbox event.

Body { baseline_determination_id, household_id, as_of } (Decision J). Fetch the baseline verdict (status + benefit_amount, plaintext on snap_determinations) via GET /v1/determinations/{id} (not /v1/snap/…​ — paths::GET_DETERMINATION); fetch the pinned corpus_hash + the enriched policy_params bundle via GET /v1/determinations/{id}/snapshot. Verify the baseline determination belongs to the requested household (reject mismatch). Assemble the household context at the supplied as_of, dispatch the snap dry-run pinned to corpus + bundle with ?audit=false. Return DryRunResult.

Completeness check at fetch: inspect the baseline snapshot’s policy_params for the full-bundle keys; if any are missing (a pre-T2-7 snapshot) or the snapshot is null, return typed NoBaselineSnapshot. Unknown corpus → CorpusUnavailable. renewals degrades both to "manual review", never a 500. SNAP-only; other programs → 422.

Load-bearing tests: same facts+corpus → baseline.verdict == dry_run.verdict; changed input → reflected; legacy/incomplete baseline → typed error, not a panic; cross-household baseline → rejected; non-SNAP → 422; no eligibility_requests row created.

Files: services/canopy-eligibility/src/{orchestrator.rs,api/handlers.rs,api/mod.rs}, contracts. OpenAPI count 7 → 8.

As-built (#680): the context-assembly extraction is two pieces — a HouseholdContext struct (replacing fetch_household_context’s 6-tuple return) + a shared `assemble_application_context — used by both determine_inner and dry_run. dry_run (+ resolve_baseline_replay + the fetch_baseline_read / fetch_baseline_snapshot / dispatch_snap_dry_run helpers) lives in orchestrator.rs; the eligibility ApplicationContext is adapted to canopy-snap’s ApplicationContext via a serde round-trip (the same boundary the live HTTP dispatch crosses), so no as_of is sent in the snap-level body (the facts are already read as-of). The "completeness check" is realized by deserializing policy_params into the typed SnapPolicyBundle (a pre-T2-7 partial bundle fails to deserialize → 422). The typed NoBaselineSnapshot / CorpusUnavailable are realized as ApiError::UnprocessableEntity (422) with distinct messages — the renewals caller degrades on the 422 status (the Rust enum does not cross the HTTP boundary), matching the established codebase pattern. DryRunRequest carries no program field, so SNAP-only is enforced by construction (the baseline is a canopy-snap determination); a non-SNAP / unknown baseline_determination_id is simply unknown to canopy-snap → 404 (the "non-SNAP → 422" test is N/A without a program selector — documented here rather than forcing a selector the consumer (renewals, SNAP-only) never needs). canopy-eligibility gained deps on canopy-contracts-snap + canopy-contracts-rules.

Subscriber: wire a renewals event subscriber in main.rs (the canopy-security subscribe_* pattern; durable queue e.g. canopy-renewals.materiality) on income.claimed/asset.claimed/expense.claimed/household.member_claimed. Use EventEnvelope.id (UUID v7) as the recert_nudges.source_event_id. Handler: derive the household — household.member_claimed carries household_id directly; income/asset/expense carry only person_id, so resolve person→household via a lightweight persons GET /v1/persons/{id}. Read the change’s valid_from from the event as the dry-run as_of (Decision J; skip retroactive valid_from < baseline as_of → manual review). Look up the active cert (get_active_certification); if none, early-return (no-op — covers the initial-application case, which fires events before any cert exists). Otherwise run the materiality flow.

Outbound auth: capture boot.service_token_source (renewals does not today) + config CANOPY_RENEWALSELIGIBILITY_URL + CANOPY_RENEWALSOIDC_SERVICE_CLIENT_ID/SECRET (note: OIDC_SERVICE_CLIENT_ID, not OIDC_CLIENT_ID). New EligibilityClient (mirror canopy-applications/src/persons_client.rs); the dry-run call carries the service identity.

Predicate + nudge: call the eligibility dry-run (baseline = cert.determination_id), apply the Decision-F predicate (threshold from [snap.materiality] via PolicyParams); insert a recert_nudges row (idempotent on (certification_id, source_event_id)). On is_material, emit renewal.material_change carrying household_id + person_id + benefit/delta/change fields.

Notice: new entry in rulesets/georgia/notices/manifest.toml + a new SNAP Typst template; add every template #inputs.<key> to default_program_data and to the entry’s program_data_keys. Confirm the 10-day advance-notice floor (ADR-010) treats an informational nudge notice correctly — exempt it from the floor if it would otherwise be rejected, documenting the exemption in the manifest entry.

Load-bearing tests: material change → nudge row + event; immaterial → no event; verdict flip with sub-threshold delta → material (OR); denied baseline → delta skipped; redelivered event → one nudge (unique key); no active cert → no-op; retroactive valid_from < baseline as_of → no-op (manual review); the ChangeInCircumstancesNotice routes as informational (is_adverse=false) and is not rejected by the 10-day floor; notice renders with real values (program_data present).

Files: services/canopy-renewals/src/{main.rs,subscriber.rs (new),eligibility_client.rs (new),api/mod.rs,params.rs,events.rs,store.rs}, new migration, rulesets/georgia/notices/manifest.toml, new .typ template, services/canopy-notices route-count test (+1).

As-built (deviations from the sketch above):

Web: surface pending recert nudges (the recert_nudges rows) in the case-detail renewals tab with worker actions (file recert / dismiss) POSTing to renewals; reuse the existing banner affordance in canopy-web/src/api/actions.rs.

CLI (ADR-007 parity — every new REST op gets a verb): canopy eligibility determine dry-run and canopy renewals nudge {list,action}. No ADR-007 amendment.

E2E: gated Playwright — author a material income change → nudge appears → file recert → ChangeInCircumstancesNotice produced; plus an immaterial-change negative path.

Docs: Antora api/canopy-{rules,eligibility,snap,renewals,notices}.adoc + data-models/ (new tables/columns, endpoints, event, notice, the enriched snapshot bundle); ADR-027/028 as-built; CHANGELOG == Unreleased; umbrella master-plan T2-7 → Done + epic &56 status. Closes #680.

Files: services/canopy-web/src/api/{actions,renewals,case_detail}.rs, tools/canopy-cli/src/cmd/*, Playwright spec, Antora pages, CHANGELOG, plans.

The worker-facing nudge endpoints are net-new in MR6. MR5 wrote the recert_nudges table + the subscriber; it added no HTTP surface. MR6 adds the two read/action endpoints the web + CLI consume — GET /v1/renewals/snap/nudges?household_id=&pending_only= (list) and POST /v1/renewals/snap/nudges/{id}/action (record a filed_recert/dismissed decision). The action is guarded WHERE is_material AND action_taken IS NULL, so a double-submit / redelivered BFF retry is a no-op (404) — the first decision stands. The worker subject is the action_by actor, forwarded by the BFF in the request body (the endpoint is service-caller-gated; the actor-in-body pattern matches DetermineRequest.requested_by). Renewals OpenAPI path count 11 → 13.

CLI: canopy eligibility dry-run, a sibling of determine (not determine dry-run). ADR-007 documents eligibility determine as a leaf verb, and clap cannot make one verb both a leaf and a subcommand group — so nesting dry-run under determine would restructure the existing eligibility determine surface and require an ADR-007 amendment. The sibling verb keeps the ADR-007 surface byte-stable with no amendment (the plan’s determine dry-run spelling was pre-implementation). renewals nudge {list,action} lands as planned.

Web: a dedicated case-detail-renewals composition section (ADR-021), not a banner. The nudge surface is a new case-detail section (programs=["snap"], row 19 span 12, empty-state when no pending nudges) with inline per-row file-recert / dismiss action forms POSTing to two new BFF action handlers (/actions/renewals/{file-recert,dismiss-nudge}) that forward to the nudge action endpoint with the worker as action_by. "Reuse the banner affordance" is realized as the post-action ?focus_section=renewals redirect (the established worker-action redirect pattern); the forms carry the standard _csrf hidden field + program-scope gate. data-recert-nudge / data-nudge-action hooks back the E2E.

E2E oracle is relational, negative leg is a bounded smoke. The material signal is a verdict-flip (a construction-extreme added wage), so the journey holds under any jurisdiction’s limits; oracles are the nudge surfacing → dropping off pending after the file (UI presence/absence) + a notice-count increase (the notice type is not UI-differentiable). The immaterial negative leg ($1 change) is a bounded-wait smoke check — the exhaustive immaterial coverage is the materiality.rs unit + proptest layer and the renewals pending-guard integration test (recert_nudge_list_and_action_enforce_pending_material_guard). Proven green live (journey-snap-income-materiality, both tests, on the demo+full stack).

Seed-reset prerequisite (#926, folded). The gated journey could not run: the demo-profile seed reset (xtask seed --reset) aborted at canopy_snap because its TRUNCATE … CASCADE cascades into the append-only determination_snapshots (the ADR-028 #678 guard), blocking all demo-profile E2E project-wide. Fixed at the architecturally-correct root — reset_tables now wraps each per-DB truncate in the guard’s documented maintenance window (BEGIN; SET LOCAL canopy.snapshot_maintenance = 'on'; TRUNCATE …; COMMIT;), generically for every DB (a harmless placeholder where no such guard exists, so it stays correct as the demo + random seeders converge; no table-exclusion or guard-disable). Filed as #926, /relate #680, fixed here as a fix(seed): commit since it is a hard prerequisite for this MR’s E2E deliverable.