[anth-volk]

Fixes #4035

Summary

• Older and reused policies copy. translate_legacy_policy no longer compares the v1 row's stored api_version with the running country package version. A v1 policy is copied whenever every parameter path it sets exists in the running catalog and its periods and values are valid, which is how the Public API already simulates an old policy. This covers each POST /{country}/policy that returns an existing row (HTTP 200) and every saved policy whose reform was saved under an older release.
• An existing copy is reused. When legacy_policy_mappings already maps the v1 policy and the source hash matches, mirror_legacy_policy_in_session returns that copy without reading the catalog or translating again (policy_created and mapping_created false). Writing the same policy again after a PolicyEngine.py or country package upgrade therefore succeeds. The branch for a mapping inserted concurrently applies the same rule.
• Every failed copy logs a fixed reason. v1_policy_mirror_operations and v1_user_policy_mirror_operations records gain failure_reason next to failure_category, for example missing_parameters, invalid_period, catalog_absent or database_error. Both fields come only from the exception type (and the translation's own reason), from two fixed enums; no policy content or exception text is logged. Successful copies log failure_reason: null. The Stage 10 runbook lists every value.
• One shared parameter check. parameters_missing_from_model lists, once each and sorted, the parameter paths a policy sets that a model lacks. The translation uses it; the follow-up PR that reports a policy's missing parameters uses the same function.
• A parameter whose period object is empty ({}) is still refused, now as empty_parameter_values instead of a misleading catalog error. A policy with more than 1,000 dated values is refused as too_many_values.

Migration notes

• Route groups covered: policy (dual-write of POST /{country}/policy) and the saved-policy copy behind /{country}/user-policy, which uses the same translation.
• What stays on the Flask/v1 path: everything. v1 responses, reads and status codes are unchanged; only the copy into the v2 tables and its log records change.
• User-visible API contract changes: none. The generated migration contracts are unchanged.
• One integration test changes expectation: a historical mapping whose v2 values differ from the stored v1 values but share its source hash is now reused unchanged instead of refused, because an existing copy is no longer translated again.

Environment variables

None. The change reads no new environment variables and touches no workflow, image or infrastructure. It acts only where DB_WRITE_POLICY=dual_write is already set.

What this PR waits for

Review only; it has no schema change and no deployment dependency.

After it deploys, an operator should confirm successful copies in the production logs (jsonPayload.attributes.metric_name="v1_policy_mirror_operations"): records with outcome=ok, including writes that returned HTTP 200, and, for any remaining errors, their new failure_reason. This changes what production's dual-write does.

Testing

Each commit was written test-first; the failing run came before the code change.

• 0acc0be99 (copy older policies): 6 tests failed first with legacy policy api_version does not match the running country package, including the two production shapes (US policy 96567 setting only gov.dol.minimum_wage, saved under us 1.633.2; UK policy 97839 setting only gov.boe.base_rate, saved under uk 2.89.2). Then 22 passed in the two files.
• 4f09b0995 (reuse an existing copy): 2 tests failed first, one with the running PolicyEngine.py 6.7.5 catalog is absent for us and one with every legacy parameter path must exist in the running catalog. Then 6 passed.
• 5122f2794 (translation reasons, shared check): the new tests failed at import (LegacyPolicyTranslationReason did not exist); then 23 passed.
• 58bd52ec1 (log failure_reason): 34 tests failed first (KeyError: 'failure_reason' and complete-record mismatches); then 76 passed.
• 3a17a5862 (review round 1: too_many_values): the new test failed (no such reason; before, the reason logged was conflicting_values); then it passed.
• e3ce42f2e (review round 1: concurrent copy on another catalog version): 1 test failed with legacy policy mapping does not match translated immutable content; then 8 passed.
• 950bab37b (review round 1: one classification table): 1 test failed ('saved_policy_mapping_conflict' == 'saved_policy_integrity'); then 109 passed in the copy test files.
• db807e809 (review round 2: typed category): the new test failed at import (PolicyCopyFailureCategory did not exist); then it passed.
• On every commit: ruff format --check ., ruff check ., uv run --frozen --extra dev mypy, python scripts/run_quality_guards.py, and the Phase 10 policy test group from docs/engineering/skills/testing.md (448 to 483 passed as tests were added). python scripts/export_migration_contracts.py leaves the generated files unchanged.
• After rebasing onto the current master: the whole tests/unit and tests/contract suites (3,378 passed).
• Not run locally: the MySQL and PostgreSQL integration suites (tests/integration/test_v2_policy_persistence.py, test_mysql_policy_dual_write.py and the other dual-write suites), because no disposable databases were available. Both changed files collect cleanly. GitHub Actions runs on this branch are cancelled at the user's request, so CI has not run them either.

No inline # noqa suppressions are added.

🤖 Generated with Claude Code