[anth-volk]

Fixes #902

Summary

Adds Modal functions that calculate one household under one to ten policies in a single call, for the US and the UK, in the versioned v2 Modal application. They reproduce the Public API's household calculation and run in their own image with no datasets and no secrets. Nothing calls them yet: they are deployed but unused until the Simulation Entrypoint gains household routes.

Each commit is one piece:

1. Household contract (policyengine_simulation_contract.household_execution): a household in the Public API's situation shape with optional axes, kept in the caller's key order (the Public API's order of errors, warnings and values depends on it); one to ten policies; a schema version; the expected PolicyEngine.py bundle; the caller's SPM settings, where leaving them out differs from sending any value (even an empty object); add_missing_variables for /calculate-full. Results carry each policy's household, warnings and SPM receipt, the applied SPM selection and the bundle provenance, or a typed failure.
2. Manifest schema version 2: each country records whether it is economy-capable and which function calculates its households. The comparison adapter gives the report coordinator only economy-capable countries. Schema version 1 readers keep reading the existing keys (active-with-region-datasets, active-with-cache, active), which the publisher still writes in schema version 1 form. Current readers use the new active-schema-2 document only while the older keys hold its schema version 1 forms, so after a rollback to code released before schema version 2, what that code publishes is read, and the next publish starts from it.
3. Input preparation (household_inputs): missing variables for /calculate-full, deprecated inputs with the Public API's warnings, unrecognized names with its error types, messages and order, and the requested values.
4. SPM (household_spm): the selection merged over the bundle's certified defaults with the Public API's codes and messages, and the compact receipt checked against the selection.
5. Observability stages for the household call, model load, input preparation and each policy's calculation.
6. Calculation (household_calculation): one simulation per policy, the Public API's reform value conversion, value formatting, null values for values that cannot be calculated (one per axis point, with a warning), and its failure messages. Country models load once per container.
7. Modal functions calculate_household_us and calculate_household_uk in a household image: the CA store, the locked packages and the source, without the bundle's datasets or the Stage 12 cache. No secrets. 2 CPUs, 4 GiB reserved and 16 GiB maximum memory, 900-second timeout, no retries, at most 20 containers.
8. Release validation: each deployed household function must calculate a one-adult, current-law household with the deployed bundle before the manifest records its household_callable.
9. Pre-merge image check: a v2 image smoke builds the coordinator, UK worker and household images, and the US worker image without its Stage 12 cache layer (only a deployment can fetch it), imports the entry points in each, and calculates the validation household in the household image.

Changes made after three structured review rounds (the second found no bugs; the third, after rebasing onto the region dataset manifest keys, found one minor issue that main already has, now documented):

• Uncertifiable SPM receipts are worded and checked in the Public API's order. The shared contract receipt model keeps its wording; the household code translates its year and metro-area messages.
• spm carries the caller's settings exactly as sent, and the function returns the Public API's SPM codes for settings sent for another country, an explicit null, or malformed settings.
• The household SPM code loads its forecast without the main path's SPM module.
• Tests that a publish after code released before schema version 2 (as a deployed revert would run) starts from what that code wrote. (When this branch was rebased onto the region dataset manifest keys from main, the schema version 2 reader took the same approach as those keys: a newer document is read only while the older keys match it.)
• The comparison backend sends the economy-capable country's simulation callable as a typed value.
• The country model loads in its own span before the SPM selection is resolved.
• More real-model tests: a chosen US SPM selection, and the validation household for both countries.
• Manifest tests store older publishers' documents with only the fields those publishers wrote, and the migration document states what a rollback to older code costs once current code publishes again.

Every known difference from the Public API is listed in the household_calculation module documentation: undefined numbers are the string "NaN" and dates are HTTP date text; the default household year is the UTC year; an age given as one value under calculate-full; an explicit null axes; a failure under any one policy fails the whole request; the request routes' error wording; and requests the contract rejects.

Tests

• Real-model tests run in the executor's PR test job: US baseline and reform in one call, US axes, US calculate-full (about 90 seconds on an idle machine), a chosen US SPM selection, the release validation household for both countries, UK axes, calculate-full, reform values given as text, unrecognized inputs, deprecated inputs, SPM refusal and an invalid household.
• Stand-in model tests cover the failure paths, SPM handling and value formatting.
• Declaration tests for the Modal functions and the household image, release validation, manifest publication, and the image smoke and its script.
• Locally, on the current head (rebased on main): the executor (1847 passed), entrypoint (665), contract (331), gateway, observability and persistence suites; Ruff format and lint, and Pyright for each changed package, on every commit; the quality guards.
• GitHub Actions: before the rebase onto the region dataset manifest keys, every check passed on commit bcedd0d4, including the PR image smoke job, which built every v2 image and calculated the validation household in the household image for the US and the UK. After the rebase, the PR image smoke job passed again on 7455b240; the other runs on the rebased commits (7455b240, 08f13016) were cancelled at the user's request, so the local runs above are the evidence for them, and CI needs to run again before merge.

Environment variables and Modal secrets

Value	Read by	Provider	How it reaches the code
Modal secrets	Household functions and household image build	None	secrets=[]; the image downloads nothing.
MODAL_ENVIRONMENT, MODAL_TASK_ID, MODAL_REGION	Household functions' telemetry identity	Modal	Set by Modal in every container.
MODAL_IDENTITY_TOKEN	Household functions' telemetry export (workload identity federation)	Modal	Set by Modal in every container. Not verified: that the workload identity provider's conditions accept tokens from the new function names. A refused token loses telemetry only; calculations are unaffected.
OBSERVABILITY_SERVICE_NAMESPACE, OBSERVABILITY_TRACE_PROJECT_ID, OBSERVABILITY_LOGGING_PROJECT_ID, OBSERVABILITY_LOG_NAME, OBSERVABILITY_GOOGLE_WORKLOAD_IDENTITY_PROVIDER, OBSERVABILITY_GOOGLE_SERVICE_ACCOUNT_EMAIL, OTEL_EXPORTER_OTLP_ENDPOINT (from OBSERVABILITY_OTLP_ENDPOINT), POLICYENGINE_OTEL_GOOGLE_AUDIENCE (from OBSERVABILITY_OTLP_GOOGLE_AUDIENCE)	Household image environment	GitHub repository variables (all eight exist)	Unchanged wiring: the env: of the "Deploy the additional versioned v2 Modal application" step in simulation-deploy.reusable.yml, baked into the image by modal_image_environment() at modal deploy, as for the other v2 images.
MODAL_TOKEN_ID, MODAL_TOKEN_SECRET	Release validation calling the household functions; the image smoke	GitHub repository and organization secrets	Unchanged: the existing env: of the v2 validation step and of the image smoke step.
PE_UK_PRIVATE_HF_READ_TOKEN	Image smoke: the UK dataset layer of the coordinator and UK worker images	GitHub organization secret	Unchanged: the image smoke step's env:; modal-image-smoke.sh stores it in the staging Modal secret pe-uk-private-hf-read-token before the smokes run. The household image does not use it.

No new variable or secret is introduced.

Before merging

• A full CI run on the current head, including the PR image smoke job (runs on the rebased commits were cancelled at the user's request).
• Review.
• Merging deploys to staging and then production. Each deployment's v2 validation now calls both household functions, and a failure stops that deployment as a failed worker validation already does.
• An operator check of the workload identity provider's conditions for the new function names (telemetry only; not required for the calculations).
• Merge coordination only: other open changes to the v2 Modal application or the v2 manifest rebase onto this one.

🤖 Generated with Claude Code