[PavelMakarchuk]

Fixes #960

Summary

The gateway's /versions says which policyengine.py (.py) version each route serves and which is latest, but not since when. This adds two optional fields to the routing state the routing publisher writes, and returns them from /versions:

• published_at ({version: ISO UTC}): when each .py version's route was first published. Republishing a version keeps its date.
• latest_since (ISO UTC or null): when latest.policyengine last changed — a publish that advances it, a forced latest, or a rollback (build_restored_routing_state).

A date is recorded only when the publish is that event (a route that did not exist, or a change of latest). The live state was written before this change, so it shows {}/null for what it already routes until the next new version is published, rather than a later, wrong date. Both fields are NotRequired, coerce_routing_state keeps valid values and drops malformed ones, and the legacy-seed merge keeps the current state's dates.

The app-v2 Deployments developer tool (PolicyEngine/policyengine-app-v2#1450) will read latest_since for the simulation API's "Live since" column; the household API already reports the equivalent, and PolicyEngine/policyengine-api#4084 does it for the API. GitHub prod deployments are no substitute: they run several times a day, including worker rebuilds that route nothing new.

Changes

• routing_publisher/state.py: published_at, latest_since, utc_now(), a now parameter on build_next_routing_state and build_restored_routing_state.
• routing_publisher/legacy.py: the legacy-seed merge keeps the current state's dates.
• Contract VersionsResponse: published_at and latest_since, documented; gateway route_resolution.py / version_routes.py read them type-safely.
• Regenerated tests/golden/openapi.json (two added fields only) and the entry project's versions_body.json smoke fixture (REGENERATE_VERSIONS_FIXTURE=1).

Testing

• New tests/version_registry/test_routing_dates.py (9 tests): first publish, republish, newer version, older version without moving latest, forced older latest, an undated state getting no wrong date, rollback, coercion, utc_now format.
• Executor tests/version_registry: 290 passed. Gateway tests: 268 passed. Contract tests: 322 passed. Entry tests: 742 passed.
• ruff check ., ruff format --check (0.15.22): passed. python -m scripts.rules pyright --sync: passed for the contract, gateway, executor, entry and other libraries; apis-integ was not checked locally because it needs the generated client. python scripts/run_quality_guards.py: all guards passed.

🤖 Generated with Claude Code

[anth-volk]

Code-quality notes from a review of this PR; the two inline comments below have the details.

1. Test coverage: the date handling added to the merge with the older per-kind version Dicts has no test, and no test runs the path deployments take (plan_routing_publication, then applying the plan) with dates.
2. Typing: published_at and latest_since are plain strings, and nothing checks that they hold the ISO 8601 UTC times the contract describes.

[anth-volk]

No test covers this: nothing merges the older per-kind version Dicts into a current state that already has published_at and latest_since and checks that both survive. A test alongside the ones in test_routing_dates would cover it.

Related: the new tests call build_next_routing_state directly. No test runs plan_routing_publication and then applies the plan with dates, which is the path the deploy workflow uses (the date is taken when the plan is computed).

[PavelMakarchuk]

Fixed in a93c3c0: test_merging_the_legacy_seed_keeps_the_current_dates merges legacy per-kind Dicts into a dated current state and checks that both dates survive. test_the_deploy_path_records_the_dates_it_plans runs plan_routing_publication, record_routing_plan and apply_routing_plan and checks the live state's dates.

[anth-volk]

published_at and latest_since are plain strings here and in RoutingState. Neither coerce_routing_state nor the gateway's routing_state_published_at / routing_state_latest_since checks the ISO 8601 UTC format these descriptions promise, so any non-empty string in the routing state reaches clients. Typing them as AwareDatetime (dict[str, AwareDatetime] and AwareDatetime | None) would make the response enforce it.

[PavelMakarchuk]

Fixed in a93c3c0: VersionsResponse types them as dict[str, AwareDatetime] and AwareDatetime | None (golden OpenAPI now says date-time). The gateway parses the stored text and drops anything that is not an ISO 8601 time with a timezone, and coerce_routing_state keeps only such times, normalized to UTC. The state itself stays JSON text in the Modal Dict. Tests cover malformed and timezone-less values in the state and in /versions.

[PavelMakarchuk]

@anth-volk thanks — both points are addressed in a93c3c0 (replies inline): tests for the legacy-seed merge and for the deploy path (plan → record → apply), and the dates are now AwareDatetime in /versions, with only timezone-aware ISO 8601 values kept in the state.

I also merged current main to resolve the changelog_entry.yaml conflict (both entries kept). Ready for another look.

[anth-volk]

Thanks, both points are addressed in a93c3c0: the new tests cover the legacy-seed merge and the plan → record → apply path, and the dates are now timezone-aware throughout.

Before merging: changelog_entry.yaml conflicts with main again (it's the only conflicting file), so it needs another merge from main.

One minor, optional point: the publisher normalizes dates to UTC, but the gateway's _aware_datetime keeps whatever offset is stored, and test_versions_reports_only_dates_with_a_timezone expects +02:00 back, while the field descriptions say "ISO 8601 UTC time". Only the publisher writes the state, so /versions shows UTC in practice; converting with .astimezone(UTC) in the gateway would make the description hold everywhere.