mcp-server-taxcode 1.3.0__tar.gz → 1.4.0__tar.gz

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/.github/dependabot.yml

@@ -2,6 +2,11 @@ version: 2
 updates:
   - package-ecosystem: "uv"
     directory: "/"
+    # Generated from uv.lock by scripts/gen_build_backend.py. The uv scan treats
+    # requirements-shaped *.txt files as pip manifests, so ignore this one.
+    # Lock bumps still land in uv.lock; regenerate the file with the script.
+    exclude-paths:
+      - "docker/build-backend.txt"
     schedule:
       interval: "weekly"
       day: "sunday"

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/AGENTS.md

@@ -139,10 +139,10 @@ When translating an API documentation page, `llm.txt`, or OpenAPI specification
    - Tool execution errors reach the client as `tools/call` results with `isError: true` and the redacted message (`tool_error`, raised `from None` after the `except` block ends, so neither `__cause__` nor `__context__` holds the original exception); `ParentAuditMiddleware` logs the same redacted message. A batch tool's per-item errors and its `batch_failed` error (`tool_failure`, raised `from None` outside any `except` block) carry redacted messages too.
    - An unknown tool stays FastMCP 4.0.11's tool result (`isError: true`). The spec's JSON-RPC `-32602` (`Unknown tool: invalid_tool_name`) is a known gap; do not change the wire format. See `COOKBOOK.md` Recipe 12.
 3. **Multi-Stage Non-Root Containers**:
-   - The `Dockerfile` must use a multi-stage build (`python:3.14-slim AS builder` $\rightarrow$ runtime, pulled from Docker Hub and pinned by digest) creating and executing under non-root `USER mcp` with virtual environment `/opt/venv`. The runtime stage carries `LABEL io.modelcontextprotocol.server.name` equal to the `server.json` `name` (MCP Registry OCI ownership check), and the default command stays stdio.
+   - The `Dockerfile` must use a multi-stage build (`python:3.14-slim-trixie AS builder` $\rightarrow$ runtime, pulled from Docker Hub and pinned by digest (both stages share the same pin); glibc is keyed by the Debian release in the tag, not the digest) creating and executing under non-root `USER mcp` with virtual environment `/opt/venv`. The runtime stage carries `LABEL io.modelcontextprotocol.server.name` equal to the `server.json` `name` (MCP Registry OCI ownership check), and the default command stays stdio.
    - Trust stores follow FastMCP's [certificate authority incident notice (October 2026)](https://github.com/PrefectHQ/fastmcp/blob/main/SECURITY.md#certificate-authority-incident-october-2026): both stages upgrade the OS `ca-certificates` package and fail the build below the patched Debian version (`ARG CA_CERTIFICATES_FLOOR`, declared once), the builder does so before any pip runs because pip trusts the OS store as well as its bundled certifi, the builder bootstraps pip 26.2.2, and `certifi>=2026.10.19` is a direct dependency. `tests/test_dockerfile.py` and CI's `docker-build` job enforce the order and the floor.
    - The pip bootstrap is hash-pinned in `docker/pip-bootstrap.txt` and installed with `--require-hashes`, so it does not depend on the TLS trust of the base image's older pip and certifi; whoever raises the pip floor updates that pin and its sha256 from PyPI (`https://pypi.org/pypi/pip/<version>/json`, the `py3-none-any` wheel's `digests.sha256`), because Dependabot does not track the file.
-   - Runtime dependencies install from `uv.lock`, so the image runs the versions CI tests: the builder installs uv from `docker/uv-bootstrap.txt` (hash-pinned, `--require-hashes`, into `/tmp/uv` outside the venv, so the runtime image has no uv), runs `uv export --locked --no-dev --no-emit-project --format requirements.txt` (base dependencies only, a hash for every package, and the build fails if `uv.lock` is stale), installs that file with pip in hash-checking mode, then installs the project build backend from `docker/build-backend.txt` (hash-pinned hatchling, uv-dynamic-versioning, and every transitive build dependency, `--require-hashes --only-binary=:all:`, into `/tmp/build-backend` outside the venv, so the runtime image has no build backend) and the project with `PYTHONPATH=/tmp/build-backend pip install --no-deps --no-build-isolation .`. Never install the project with its dependencies (`pip install .`), which resolves them fresh at build time. Dependabot's weekly `uv` updates bump the uv pin and rewrite its sha256 values, writing one for every wheel and the sdist published for that version. Whoever changes `[tool.uv] required-version` keeps the uv pin within it, and a hand bump takes a sha256 for every wheel and the sdist from `https://pypi.org/pypi/uv/<version>/json` (`digests.sha256`); the manylinux x86_64 and aarch64 wheels are the ones the image build installs. The build-backend pins are the `build-backend` dependency group in `pyproject.toml` (exact versions inside the `[build-system]` ranges, not installed by default), so `uv.lock` carries their closure with hashes. After `uv lock`, `uv run python scripts/gen_build_backend.py` rewrites `docker/build-backend.txt` from `uv.lock` (`--check` reports drift instead), and `tests/test_build_backend_lock.py` fails if the file, the lock or the ranges disagree. Dependabot does not track that file (no `pip` ecosystem entry covers `docker/` in `.github/dependabot.yml`). `tests/test_dockerfile.py` enforces the install steps and the pins.
+   - Runtime dependencies install from `uv.lock`, so the image runs the versions CI tests: the builder installs uv from `docker/uv-bootstrap.txt` (hash-pinned, `--require-hashes`, into `/tmp/uv` outside the venv, so the runtime image has no uv), runs `uv export --locked --no-dev --no-emit-project --format requirements.txt` (base dependencies only, a hash for every package, and the build fails if `uv.lock` is stale), installs that file with pip in hash-checking mode, then installs the project build backend from `docker/build-backend.txt` (hash-pinned hatchling, uv-dynamic-versioning, and every transitive build dependency, `--require-hashes --only-binary=:all:`, into `/tmp/build-backend` outside the venv, so the runtime image has no build backend) and the project with `PYTHONPATH=/tmp/build-backend pip install --no-deps --no-build-isolation .`. Never install the project with its dependencies (`pip install .`), which resolves them fresh at build time. Dependabot's weekly `uv` updates bump the uv pin and rewrite its sha256 values, writing one for every wheel and the sdist published for that version. Whoever changes `[tool.uv] required-version` keeps the uv pin within it, and a hand bump takes a sha256 for every wheel and the sdist from `https://pypi.org/pypi/uv/<version>/json` (`digests.sha256`); the manylinux x86_64 and aarch64 wheels are the ones the image build installs. The build-backend pins are the `build-backend` dependency group in `pyproject.toml` (exact versions inside the `[build-system]` ranges, not installed by default), so `uv.lock` carries their closure with hashes. After `uv lock`, `uv run python scripts/gen_build_backend.py` rewrites `docker/build-backend.txt` from `uv.lock` (`--check` reports drift instead), and `tests/test_build_backend_lock.py` fails if the file, the lock or the ranges disagree. The file is generated from `uv.lock` by `scripts/gen_build_backend.py`, must never be edited by hand, and the `uv` Dependabot entry excludes it via `exclude-paths`. `tests/test_dockerfile.py` enforces the install steps and the pins.
    - Lowering `CA_CERTIFICATES_FLOOR` with `--build-arg` is unsupported; the build-arg exists only so CI can raise it for the negative floor check, and CI and the release workflow never pass it otherwise.
 4. **Registry Metadata Constraint**:
    - In `server.json`, the root `description` must be **strictly $\le$ 100 characters** to pass MCP Registry schema validation (longer strings trigger HTTP 422 errors).
@@ -211,6 +211,6 @@ coderabbit review --agent --uncommitted
 
 ## 🔄 CI & Releases
 
-CI is defined in `.github/workflows/ci.yml` (jobs: `lint-and-types`, `test` on Python 3.11–3.14, `tool-contract`, `build-check`, `docker-build` (builds the image without pushing, checks its MCP server-name label against `server.json`, checks that the runtime image has the project and none of the build-only packages (runtime dependencies such as `packaging` stay), checks that the image answers `initialize` and `tools/list` over stdio with no network, and checks that the builder stage fails at its `ca-certificates` floor check, before any pip step, when the floor is above the installed version), and `drift-check` (the same OpenAPI drift check as its own job; scheduled and manual runs only)). It runs on pushes and pull requests to `main`, weekly on `main` on Sunday at 15:53 America/New_York (`schedule` with `timezone`, after the Sunday 09:30 America/New_York Dependabot run in `.github/dependabot.yml`), and on manual dispatch (`workflow_dispatch`); the weekly run exists because merges by `dependabot-automerge.yml` use `GITHUB_TOKEN`, and pushes made with `GITHUB_TOKEN` don't trigger push workflows, so those merges get no `push` run. Run the commands above before opening a PR. `dependabot-automerge.yml` turns on squash auto-merge only for Dependabot PRs whose highest update is minor or patch; major updates wait for a human review. Docker base image updates (`package-ecosystem` `docker`) never auto-merge and always wait for a human review: Dependabot's docker ecosystem can move the image tag, not just its digest (for example `python:3.12-slim` to `python:3.14-slim`, a Python runtime upgrade that Dependabot labels a minor update), so the job logs a notice and leaves the PR open.
+CI is defined in `.github/workflows/ci.yml` (jobs: `lint-and-types`, `test` on Python 3.11–3.14, `tool-contract`, `build-check`, `docker-build` (builds the image without pushing, checks its MCP server-name label against `server.json`, checks that the runtime image has the project and none of the build-only packages (runtime dependencies such as `packaging` stay), checks that the image answers `initialize` and `tools/list` over stdio with no network, and checks that the builder stage fails at its `ca-certificates` floor check, before any pip step, when the floor is above the installed version), and `drift-check` (the same OpenAPI drift check as its own job; scheduled and manual runs only)). It runs on pushes and pull requests to `main`, weekly on `main` on Sunday at 15:53 America/New_York (`schedule` with `timezone`, after the Sunday 09:30 America/New_York Dependabot run in `.github/dependabot.yml`), and on manual dispatch (`workflow_dispatch`); the weekly run exists because merges by `dependabot-automerge.yml` use `GITHUB_TOKEN`, and pushes made with `GITHUB_TOKEN` don't trigger push workflows, so those merges get no `push` run. Run the commands above before opening a PR. `dependabot-automerge.yml` turns on squash auto-merge only for Dependabot PRs whose highest update is minor or patch; major updates wait for a human review. Docker base image updates (`package-ecosystem` `docker`) never auto-merge and always wait for a human review: Dependabot's docker ecosystem can move the image tag, not just its digest (for example `python:3.12-slim-trixie` to `python:3.14-slim-trixie`, a Python runtime upgrade that Dependabot labels a minor update), so the job logs a notice and leaves the PR open.
 
 `release.yml` runs on `v*` tag pushes only: it creates the GitHub Release, then builds the container image, pushes it to GHCR, attests it, and publishes to the MCP Registry. In the template repo the image is built only (no push), and the attest and registry jobs skip. Release procedure (tag-based versioning, release notes, pre-tag checks): **`COOKBOOK.md`** Recipes 1–2; product-repo migration steps: Recipe 9.

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/CONTRIBUTING.md

@@ -9,6 +9,7 @@ Thank you for your interest in contributing!
 5. Open a Pull Request. Merges are performed via **Squash Merge** with Conventional Commit titles (`feat:`, `fix:`, `docs:`, `chore:`).
 6. Changing statute or publication rows? Follow "Adding or changing a row" below and run `uv run python scripts/build_catalog.py --check`.
 7. Do not edit version numbers or `CHANGELOG.md`: the git tag is the version, and GitHub Releases are the changelog. The squash commit message is the PR body, so a breaking (`feat!:` / `fix!:`) PR ends its body with one `BREAKING CHANGE:` final paragraph that lists the breaking items, with no migration steps.
+8. Do not edit `docker/build-backend.txt` by hand.
 
 ## Adding or changing a row
 
@@ -58,7 +59,7 @@ Every deduction, exemption, bracket, rate and per-year value the compliance tool
 - `brackets` and `rates` are lists tried in order: the first step whose `over` the taxable income exceeds (or whose `from_year` the tax year has reached) applies, and the last step's `over` or `from_year` is `null`. Filing-status values are `{"single": ..., "mfj": ...}`.
 - Each `rates` step also carries its prose: a `flat_by_year` step (CO, NC) its whole `rate_desc`, and a `georgia` step the `law` that set that year's rate, which both Georgia answers cite. Georgia's flat rate starts with tax year 2024, so an earlier tax year gets the oldest step and its answers say they are an estimate.
 - Each table has a `source_url` and a `rate_table` entry in `manifest/<code>.json` with the same `url`. A table whose numbers have not been checked against official text keeps `"not_recorded"` in both. Record a source only once it has been checked, and only an official one: `url` is the document the brackets were read from, `retrieved` the day it was fetched and `content_sha256` the hash of the fetched bytes (`"not_recorded"` when the bytes could not be kept).
-- `registry` tables keep their original keys. A `_YYYY` suffix holds the value from that tax year on, and the unsuffixed key covers the years before. Never copy a current value into an earlier year.
+- `registry` tables keep their original keys. A `_YYYY` suffix holds the value from that tax year on, and the unsuffixed key covers the years before. Never copy a current value into an earlier year. A year with no sourced amount is a `not_recorded` entry on `params`, `{"param", "tax_year", "reason"}`, omitted when empty, and the rate table's manifest entry repeats that list after `year_sources`. `param` is the base series (`deduction`, `brackets`, `rates`, `credit_base`, ...); one entry covers both filing statuses. The lookup stops on that exact year. A later year with no marker still uses the last real `_YYYY` value. The catalog rejects a marker on a year the tools read for a different year (Georgia's 2024 and 2026 standard deduction, and Georgia's 2026 rate step) and a Georgia `standard_deduction` marker for a year before 2018, which reads the 2024 amount. A table with no `_YYYY` key and no `rates` step cannot mark a year. The federal standard deduction table has no such list.
 - The `flat_with_surtax` table's `surtax`, the `capital_gains_excise` table's `capital_gains_deduction` and the `brackets_cumulative` table's `brackets` and `exemption` follow the same convention: `surtax_2024`, `capital_gains_deduction_2024`, `brackets_2025` or `exemption_2025`, after the model's own fields with years ascending for each name, holds the value from that year on, and the unsuffixed key keeps the earlier years. The `capital_gains_excise` table's `tier` (`{"over": ..., "rate": ...}`, an additional rate on the taxable gains over `over`) takes only `tier_YYYY` keys and doesn't apply before the first one. The `georgia` table's `standard_deduction` and `retirement_exclusion` take `_YYYY` keys the same way (`standard_deduction_2026`, `retirement_exclusion_2027`), after `rates`, years ascending. A tax year after `GA_LAST_FIXED_YEAR` (the last year whose deduction and rate HB 463 of 2026 fixes) uses that year's figures and is labeled an estimate, because HB 463's later increases and rate cuts depend on revenue tests.
 - Registry deductions take `_2024`, `_2025` and `_2026`. Registry `brackets` and `rate_desc` take `brackets_YYYY` and `rate_desc_YYYY` for 2024 to 2030, and the four `credit_base_*` / `credit_phaseout_*` amounts take `_2025`. Each needs its unsuffixed key and comes after it, years ascending; `brackets_YYYY` is validated like `brackets` and doesn't count as one of the three graduated keys below. A tax year after `MS_LAST_ENACTED_RATE_YEAR`, `UT_LAST_CREDIT_AMOUNT_YEAR`, `NE_LAST_PUBLISHED_SCHEDULE_YEAR` or `OH_LAST_FIXED_SCHEDULE_YEAR` (tied by tests to the last year each table holds) carries that table's figures forward and is labeled an estimate in its rate prose.
 - A graduated `registry` table says how it taxes income below its top bracket with exactly one of two keys. `brackets` is the state's official marginal schedule (`over` and `rate` only, the lowest step's `over` is `null`), and replaces the `top_*`, `zero_*` and `middle_*` keys. `middle_rate` is a single statutory rate for the middle band. Every `evaluate_state_residency` answer carries `middle_rate_is_estimate` (always `false`; the former 65%-of-top stand-in is gone). Never invent a middle-band rate where an official schedule exists.

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/Dockerfile

@@ -18,7 +18,7 @@
 ARG CA_CERTIFICATES_FLOOR=20250419+deb13u1
 
 # ─── Stage 1: Builder ─────────────────────────────────────────────────────────
-FROM python:3.14-slim@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS builder
+FROM python:3.14-slim-trixie@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS builder
 
 ARG CA_CERTIFICATES_FLOOR
 RUN apt-get update && \
@@ -75,7 +75,7 @@ RUN pip install --no-cache-dir --require-hashes --only-binary=:all: -r /tmp/pip-
     PYTHONPATH=/tmp/build-backend pip install --no-cache-dir --no-deps --no-build-isolation .
 
 # ─── Stage 2: Runtime ─────────────────────────────────────────────────────────
-FROM python:3.14-slim@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS runtime
+FROM python:3.14-slim-trixie@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS runtime
 
 # MCP Registry ownership check for the OCI package: must equal server.json "name".
 # https://modelcontextprotocol.io/registry/package-types#docker%2Foci-images

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-taxcode
-Version: 1.3.0
+Version: 1.4.0
 Summary: Enterprise Model Context Protocol (MCP) server for Tax Code
 Project-URL: Homepage, https://github.com/christianclaudio/mcp-server-taxcode
 Project-URL: Documentation, https://github.com/christianclaudio/mcp-server-taxcode#readme
@@ -22,17 +22,17 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
-Requires-Dist: certifi>=2026.10.19
+Requires-Dist: certifi>=2026.10.23
 Requires-Dist: duckdb>=1.5.6
-Requires-Dist: fastmcp>=4.1.5
+Requires-Dist: fastmcp>=4.1.8
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp>=2.3.0
 Requires-Dist: pydantic-settings>=2.15.0
 Requires-Dist: pydantic>=2.13.5
 Provides-Extra: code-mode
-Requires-Dist: fastmcp[code-mode]>=4.1.5; extra == 'code-mode'
+Requires-Dist: fastmcp[code-mode]>=4.1.8; extra == 'code-mode'
 Provides-Extra: dev
-Requires-Dist: fastmcp[code-mode]>=4.1.5; extra == 'dev'
+Requires-Dist: fastmcp[code-mode]>=4.1.8; extra == 'dev'
 Requires-Dist: mypy>=2.4.0; extra == 'dev'
 Requires-Dist: opentelemetry-sdk>=1.45.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/fastmcp.json

@@ -7,11 +7,12 @@
   "environment": {
     "dependencies": [
       "mcp>=2.3.0",
-      "fastmcp>=4.1.5",
-      "certifi>=2026.10.19",
-      "httpx>=0.28.0",
-      "pydantic>=2.10.0",
-      "pydantic-settings>=2.7.0"
+      "fastmcp>=4.1.8",
+      "certifi>=2026.10.23",
+      "httpx>=0.28.1",
+      "pydantic>=2.13.5",
+      "pydantic-settings>=2.15.0",
+      "duckdb>=1.5.6"
     ]
   },
   "deployment": {

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/pyproject.toml

@@ -27,11 +27,11 @@ classifiers = [
 ]
 dependencies = [
     "mcp>=2.3.0",
-    "fastmcp>=4.1.5",
+    "fastmcp>=4.1.8",
     # certifi floor from FastMCP's October 2026 certificate authority incident notice:
     # https://github.com/PrefectHQ/fastmcp/blob/main/SECURITY.md#certificate-authority-incident-october-2026
     # httpx verifies upstream TLS against certifi's bundle.
-    "certifi>=2026.10.19",
+    "certifi>=2026.10.23",
     "httpx>=0.28.1",
     "pydantic>=2.13.5",
     "pydantic-settings>=2.15.0",
@@ -42,10 +42,10 @@ dependencies = [
 # Code Mode is optional: FastMCP ships its pydantic-monty sandbox as the code-mode extra.
 # Users install mcp-server-<name>[code-mode]; dev repeats the same pin so tests run execute.
 code-mode = [
-    "fastmcp[code-mode]>=4.1.5",
+    "fastmcp[code-mode]>=4.1.8",
 ]
 dev = [
-    "fastmcp[code-mode]>=4.1.5",
+    "fastmcp[code-mode]>=4.1.8",
     "pytest>=9.1.1",
     "pytest-asyncio>=1.4.0",
     "pytest-cov>=7.1.0",

{mcp_server_taxcode-1.3.0 → mcp_server_taxcode-1.4.0}/scripts/gen_build_backend.py

@@ -3,7 +3,8 @@
 The Dockerfile installs the project build backend from that file with ``--require-hashes``,
 outside the runtime venv. uv.lock already records the group's closure with every wheel hash,
 so this keeps only the wheels the base image can install: ``py3-none-any``, or for compiled
-packages the manylinux x86_64 and aarch64 wheels for the base image's CPython ABI.
+packages one manylinux x86_64 wheel and one manylinux aarch64 wheel for the base image's CPython ABI
+whose glibc floor that image can load. A higher floor installs and then fails to load.
 
 Usage: ``uv run python scripts/gen_build_backend.py`` writes the file; ``--check`` exits 1 and
 lists the differences instead. tests/test_build_backend_lock.py runs the same check.
@@ -25,6 +26,29 @@ ROOT = Path(__file__).resolve().parent.parent
 GROUP = "build-backend"
 TARGET = ROOT / "docker" / "build-backend.txt"
 ARCHES = ("x86_64", "aarch64")
+# glibc of the Debian release named by the base image tag (python:X.Y-slim-<release>).
+# The digest is not the key. Sources are the libc6 packages for each release:
+# trixie (Debian 13): https://packages.debian.org/trixie/libc6 is 2.41
+# bookworm (Debian 12): https://packages.debian.org/bookworm/libc6 is 2.36
+_DEBIAN_GLIBC: dict[str, tuple[int, int]] = {
+    "trixie": (2, 41),
+    "bookworm": (2, 36),
+}
+# PEP 600: manylinux_X_Y_<arch> means glibc X.Y. Legacy aliases: manylinux1 = 2.5
+# (PEP 513), manylinux2010 = 2.12 (PEP 571), manylinux2014 = 2.17 (PEP 599).
+_MANYLINUX_ALIAS: dict[str, tuple[int, int]] = {
+    "manylinux1": (2, 5),
+    "manylinux2010": (2, 12),
+    "manylinux2014": (2, 17),
+}
+# The image reference ends at whitespace (`` AS builder``) or end of line. Without
+# that anchor a longer token matches as a prefix, and image_glibc then accepts it
+# or reports the wrong error.
+_FROM_SLIM = re.compile(
+    r"^FROM python:\d+\.\d+-slim(?:-(?P<release>[A-Za-z0-9.]+))?"
+    r"(?:@(?P<digest>sha256:[0-9a-f]{64}))?(?=\s|$)",
+    re.MULTILINE,
+)
 HEADER = (
     "# Build backend for the Dockerfile project install: the build-backend dependency group in",
     "# pyproject.toml and its closure from uv.lock. Generated by scripts/gen_build_backend.py;",
@@ -42,6 +66,37 @@ def base_python(dockerfile: str) -> str:
     return versions.pop()
 
 
+def image_glibc(dockerfile: str) -> tuple[int, int]:
+    """Return the glibc of the Debian release named by the base image tag.
+
+    ``base_python`` still requires one ``python:X.Y-slim`` version. The floor is
+    the ``_DEBIAN_GLIBC`` entry for the release suffix, so a digest change within
+    that release does not move it. An unpinned base, a tag with no release, a
+    ``FROM python:`` line the pattern does not match, two FROM lines that name
+    different releases, or an unknown release raises ``ValueError``.
+    """
+    base_python(dockerfile)
+    images = list(_FROM_SLIM.finditer(dockerfile))
+    # Every FROM python: line has to match. A malformed stage must not disappear
+    # behind a valid one.
+    from_python = re.findall(r"^FROM python:", dockerfile, re.MULTILINE)
+    if len(from_python) != len(images):
+        raise ValueError("expected a pinned python:X.Y-slim-<release>@sha256 base image")
+    if not images or any(image.group("digest") is None for image in images):
+        raise ValueError("expected a pinned python:X.Y-slim-<release>@sha256 base image")
+    releases = [image.group("release") for image in images]
+    if any(release is None for release in releases):
+        raise ValueError("python:X.Y-slim has no Debian release suffix")
+    names = sorted({release for release in releases if release is not None})
+    if len(names) != 1:
+        raise ValueError(f"expected one Debian release, found {names}")
+    release = names[0]
+    glibc = _DEBIAN_GLIBC.get(release)
+    if glibc is None:
+        raise ValueError(f"Debian release {release} has no glibc entry; update _DEBIAN_GLIBC")
+    return glibc
+
+
 def _environment(python: str, machine: str) -> dict[str, str]:
     return {
         "implementation_name": "cpython",
@@ -103,7 +158,34 @@ def _closure(lock: dict[str, Any], python: str) -> list[dict[str, Any]]:
     return [seen[name] for name in sorted(seen)]
 
 
-def _digests(package: dict[str, Any], python: str) -> list[str]:
+def _manylinux_tag(platform: str) -> tuple[tuple[int, int], str] | None:
+    """Return ``(glibc floor, arch)`` for a manylinux tag, or None for anything else."""
+    perennial = re.fullmatch(r"manylinux_(\d+)_(\d+)_(.+)", platform)
+    if perennial:
+        floor = (int(perennial.group(1)), int(perennial.group(2)))
+        return floor, perennial.group(3)
+    legacy = re.fullmatch(r"(manylinux2010|manylinux2014|manylinux1)_(.+)", platform)
+    if legacy is None:
+        return None
+    return _MANYLINUX_ALIAS[legacy.group(1)], legacy.group(2)
+
+
+def _loads_on(platform: str, arch: str, glibc: tuple[int, int]) -> bool:
+    """True when ``platform`` is manylinux for ``arch`` and its floor is <= ``glibc``."""
+    parsed = _manylinux_tag(platform)
+    if parsed is None:
+        return False
+    floor, tag_arch = parsed
+    return tag_arch == arch and floor <= glibc
+
+
+def _digests(package: dict[str, Any], python: str, glibc: tuple[int, int]) -> list[str]:
+    """Return wheel hashes the base image can install.
+
+    A ``py3-none-any`` wheel wins. Otherwise exactly one cp wheel per architecture,
+    counting a wheel when any dotted manylinux tag for that arch has a glibc floor
+    at or below ``glibc``. musllinux never qualifies.
+    """
     abi = "cp" + python.replace(".", "")
     universal: list[str] = []
     native: dict[str, list[str]] = {arch: [] for arch in ARCHES}
@@ -116,7 +198,7 @@ def _digests(package: dict[str, Any], python: str) -> list[str]:
         elif py_tag == abi and abi_tag == abi:
             platforms = platform_tag.split(".")
             for arch in ARCHES:
-                if any(p.startswith("manylinux") and p.endswith(arch) for p in platforms):
+                if any(_loads_on(platform, arch, glibc) for platform in platforms):
                     native[arch].append(digest)
     if universal:
         return sorted(universal)
@@ -128,9 +210,14 @@ def _digests(package: dict[str, Any], python: str) -> list[str]:
 def expected() -> dict[str, tuple[str, list[str]]]:
     """Map package name to (version, sha256 digests) for the group closure in uv.lock."""
     lock = tomllib.loads((ROOT / "uv.lock").read_text(encoding="utf-8"))
-    python = base_python((ROOT / "Dockerfile").read_text(encoding="utf-8"))
+    dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
+    python = base_python(dockerfile)
+    glibc = image_glibc(dockerfile)
     return {
-        canonicalize_name(package["name"]): (package["version"], _digests(package, python))
+        canonicalize_name(package["name"]): (
+            package["version"],
+            _digests(package, python, glibc),
+        )
         for package in _closure(lock, python)
     }