## TL;DR
Poetry resolved the newest wheel without honoring the python constraint the way you expected, landing a 3.12-only wheel on a 3.10 image. Pin the constraint tightly in pyproject, verify with poetry check, and make the CI image match the constraint.

## Error
```text
agent's poetry update ignored the python constraint in pyproject.toml  -  it installed a wheel requiring python 3.12 on a 3.10 image
```

## Steps
1. Confirm the mismatch: check the installed package's requires-python metadata against the python constraint in pyproject.toml and the CI image version.
   Expected output: The wheel needs 3.12 while the project and image are 3.10.
2. Tighten the constraint in pyproject.toml to the intended range (for example 3.10.x only, excluding 3.11 and above) so resolution cannot pick a 3.12-only wheel.
   Expected output: The constraint excludes the incompatible wheel.
3. Run poetry check and poetry lock --no-update, then reinstall and verify the resolved versions honor the constraint.
   Expected output: The lockfile resolves only wheels compatible with 3.10.
4. Align the CI and deploy images to the same Python version the constraint allows.
   Expected output: The image and the constraint agree, so the mismatch cannot recur.
5. Add a CI step that asserts the running Python satisfies the pyproject constraint before tests.
   Expected output: A future drift fails fast with a clear message.

## When to use
- A wheel's requires-python exceeds the project or image version
- Poetry resolved a version your runtime cannot import
- You are aligning Python versions across pyproject, lockfile, and CI

## When not to use
- Intentionally raising the Python floor; update pyproject and images together
- A broken wheel unrelated to version constraints
- System-Python versus venv confusion; that is environment setup

### Variant phrasings
#### poetry installed a package requiring a newer python
#### wheel requires python 3.12 but project uses 3.10
#### poetry lock ignoring python version constraint

## Why it happens
The constraint was loose enough (or expressed in a way the resolver treated loosely) that the newest wheel won resolution. The install succeeded because pip and Poetry install wheels without running them; the failure only appears at import or at a metadata check, far from the bump.

## Edge cases
- `python = "^3.10"` allows 3.11 and 3.12; use an upper bound if you mean 3.10 only.
- Poetry's python constraint and the locked packages can disagree after a partial update; always re-lock fully.
- Docker images tagged `3.10` still move under you; pin the full image digest for reproducibility.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_e9R3LJEeiI6ioBTd1TyH6A