Refactor within ruff's complexity limits, then select every ruff rule (ALL)

[anth-volk]

Fixes #803

Same-Repository Draft PR Check

• This PR is a draft.
• This PR is from a branch in PolicyEngine/policyengine-sim-api, not a personal fork.

Summary

Phase 1 step 1.8, group 8b, the last group: complexity refactors, then select = ["ALL"]. Stacked on #802. This completes step 1.8.

Every function over ruff's complexity limits is refactored, not suppressed. Each refactor is preceded by a commit that adds characterization tests pinning the current behaviour. Every commit passes ruff and the quality guards.

• Contract and persistence libraries:

  • ComparisonReportRecord.validate_state keeps its Pydantic signature and is split into report and comparison checks.
  • The live column-type check is split into enum and plain-type checks.
  • URI, version and name-length limits are named constants.

• Entry:

  • create_app (complexity 52, 144 statements) keeps every route's name, decorators, parameters and registration order. The shared behaviour moves into _EntryRuntime, and Stage 12 error logs still record only the error type.
  • Settings validation is split into caller-auth, old-gateway and Stage 12 checks.
  • The Stage 12 adapter is split into eligibility checks and a report builder.
  • Stage 12 dispatch takes a prepared report, an origin and a worker version.

• Gateway: active-state route resolution is split into pinned, latest and requested-version steps.

• Executor: long argument lists become small frozen groups, including:

  • artifact key inputs;
  • baseline identity requests;
  • precompute function handles;
  • national-reduce inputs;
  • fan-out poll backoff;
  • qualification runners and tolerances;
  • Stage 12 coordinator invocation and dependencies;
  • child spawn requests;
  • worker seams.

  Stage 12 coordination (complexity over 10, 11 arguments, 109 statements) becomes a _ReportCoordination class with claim, plan, dispatch, wait and aggregate phases. The Stage 12 parity checks are split by entity, column and report value. The image artifact fetch is split into freshness, credential and download steps.

• Code from Expose the certified dataset SHA-256 and assert the served identity at deploy #743, Gate releases on a numerical sentinel and make them reversible #744 and Release Stage 12 database sessions and keep original failures visible #789, which merged while this was in progress, is refactored the same way:

  • release_sentinel.check_deployment (JobPolling, a _Deployment with per-case and job-wait steps, HTTPStatus.OK).
  • The routing publisher's main: one command function per mode, with the same precedence. Its --help output is byte-identical.
  • restore_routing_plans.
  • The package updater's bundle_versions and verify_dispatch.
  • open_connection_with_retry (RetryTiming).
  • The workflow-expression and routing-command test helpers.

  Release Stage 12 database sessions and keep original failures visible #789's original-failure reporting and session release are kept inside the new coordination phases.

• Kept with a reason (3): # noqa: PLR0913 on three library functions other projects import: create_initial_batch_state, resolve_spm_selection and init_simulation_observability. Modal function signatures, local entrypoints, FastAPI routes and Pydantic validators keep their signatures.

• Rules tool: takes the Public API's group 8b refactor (Refactor tests, scripts and the rules tool, then select every ruff rule (ALL) policyengine-api#3934). Each repository owns its copy; this one is currently identical. Its tests went from 74 to 109.

• ALL:

  • ruff.toml selects every rule, and ignores only the two that conflict with ruff format (COM812, ISC001) and one of each mutually exclusive docstring pair (D203, D213).
  • The per-file exemptions are unchanged.
  • ALL found nothing that wasn't already fixed.
  • sim.quality.ruff-lint lists ALL.
  • The rules-registry skill doc says every rule applies, and that a ruff upgrade PR fixes any new rule's violations.

Noticed, not changed: in release_sentinel, a job that fails but still returns an object result has its values compared anyway. The new tests pin that existing behaviour. It may be worth confirming it's intended.

Testing

Every suite passes:

Project	Base	This PR
fastapi	14	14
contract	147	201
observability	30	30
stage12	17	38
entry	444	528
gateway	230	247
executor	1,060	1,265

The additions are the characterization tests: 381 in all. The gateway has 1 test deselected and the executor 22 skipped and 3 deselected, as on the base. The grouping renamed 7 parametrized test IDs in the entry's deploy-script tests, and 34 in the gateway's SPM route tests.

• OpenAPI: the gateway golden OpenAPI test passes, with tests/golden unchanged. The entry, executor and gateway OpenAPI dumps are byte-identical to the base.
• Lint: ruff check . with ALL gives 0 findings, and ruff format --check . passes.
• Rules tool and guards: the rules tool's 109 tests pass on Python 3.11. The quality guards pass at every commit, and the gate test passes at the tip.
• Modal images: files in the executor and gateway images change, all inside function bodies or module helpers. src/modal/app.py is untouched.
• CI/CD: no environment-variable read was added or changed; some reads only moved within changed files.
  • RELEASE_PAYLOAD is set from the check-policyengine-updates.yml step env:.
  • The sentinel's SIMULATION_TEST_AUTH_* values come from the SIMULATION_ENTRYPOINT_* secrets through secrets: inherit.
  • The image fetch's GOOGLE_APPLICATION_CREDENTIALS_JSON comes from the gcp_secret Modal secret.
  • I haven't checked that those secrets exist in the GitHub and Modal settings.
• CI: above the bottom of its stack, so only CI complete runs until the PRs below merge.

🤖 Generated with Claude Code