Body
Build the Luxembourg (LU) population synthesis QA cycle 1 review bundle.
Project root: /home/synthestat
Country: LU
Target geography: finest available official geography supported by existing Synthestat source/building/geography layers
Release mode: internal research review
Parent orchestrator: t_59cdb7d9
Required context:
- Read /home/synthestat/docs/SOUL.md and /home/synthestat/docs/contracts/population_review_bundle.md before doing substantive work.
- Reuse existing Synthestat modules/CLI paths; do not duplicate country-specific synthesis logic.
- LU STATEC live inventory may need an explicit --statec-base-url override unless a statec/lu_statec provider exists in config/sources.yaml; if unavailable, log the missing provider/degradation rather than fabricating data.
Goal:
Generate a contract-complete review bundle under /home/synthestat/output/runs/LU/<deterministic_run_id>/ for the best currently supportable 1:1 synthetic population slice: persons in households, households in dwellings, dwellings/building assignments where available. Include hidden/weakly measured population overlays only where evidence supports them; otherwise emit unavailable.json with explicit reason.
Mandatory bundle files per docs/contracts/population_review_bundle.md:
- synthetic_persons.parquet|csv
- synthetic_households.parquet|csv
- synthetic_dwellings.parquet|csv OR unavailable.json with reason
- synthetic_building_assignments.parquet|csv OR unavailable.json with reason
- hidden_population_overlays.parquet|csv OR unavailable.json with reason
- work_school_assignments.parquet|csv OR unavailable.json with reason
- build_manifest.json
- constraint_residuals.json
- distribution_diagnostics.json
- household_diagnostics.json
- dwelling_building_diagnostics.json
- assignment_diagnostics.json
- geography_quality_tiers.json
- uncertainty_summary.json
- source_provenance.json
- model_notes.md
Non-negotiables:
- HARD constraints must not break. If exact HARD constraints cannot be supported, do not fake them; make the output invalid/blocking and document why.
- Every model-based estimate must carry uncertainty bounds or explicit quality/degradation flags.
- Hidden-population overlays must not silently rewrite de jure population constraints.
- Fine-geography sparse variables such as occupation/industry are model-driven unless directly measured and must be flagged.
- Log every missing source, relaxed constraint, failed download/probe, degraded zone, and unavailable layer.
Allowed write paths:
- /home/synthestat/output/runs/LU/<run_id>/
- /home/synthestat/workspace/manager_handoffs/modeller/
- optional durable implementation/review notes under /home/synthestat/docs/wiki/outputs/
Definition of done:
1. A review bundle exists at /home/synthestat/output/runs/LU/<run_id>/ and contains every required file or an explicit unavailable.json replacement where the contract allows it.
2. build_manifest.json includes country, run_id, created_at, project_root, git_commit/dirty marker, deterministic random_seed, source/geography/crosswalk versions where known, constraints_used/relaxed, zones_degraded, hidden_population_scope, assignment_scope, and known_limitations.
3. constraint_residuals.json proves HARD constraints pass exactly or documents a blocking invalid-output state.
4. uncertainty_summary.json and source_provenance.json are populated enough for reviewer audit.
5. Write a concise modeler handoff in /home/synthestat/workspace/manager_handoffs/modeller/ naming the bundle path, run_id, counts, known limitations, unavailable layers, and commands/tests run.
6. Complete this card with structured metadata including bundle_path, run_id, tests_run/commands_run, and key limitations.