Add sync_toolchains/check_toolchains actions and Python interpreter derivation (ADR-0053)

Implements the toolchain-axis derivation promised by the previous
commit's requires-python backfill: fine_envs.sync_toolchains derives
each env's toolchain axis from the project's declared support range
and materializes it into the project definition file, dispatching per
language to a subaction (fine_python_lang.sync_python_interpreters).
check_toolchains re-derives with save=False and fails on drift, for
wiring into precommit/CI (bridged via fine_git_hooks).

The Python subaction expands requires-python against the set of
interpreters uv can actually obtain (list_obtainable_toolchains /
list_obtainable_python_interpreters, backed by
fine_python_uv.UvListObtainablePythonInterpretersHandler), so an open
upper bound is resolved against what is installable rather than
rejected or left to silently backtrack. The axis is materialized
rather than recomputed at read time so config resolution stays a pure
read and a preset bump can't change a project's matrix without a
diff — see docs/reference/actions.md and ADR-0053 for the full
rationale on both actions and the derive/materialize/check shape.

Author: Aksem

docs/guides/developing-finecode.md

@@ -352,6 +352,16 @@ python -m finecode prepare-envs
 
 To update lock files, run `lock_dependencies` locally or in a scheduled CI job and commit the result. For multi-platform projects, use a CI matrix to generate lock files on each target platform.
 
+## `requires-python`: no upper bound
+
+FineCode's own packages declare a **lower bound only** on `requires-python` (e.g. `>=3.11`), never an upper bound (`< 3.15`, `<= 3.14`).
+
+An upper bound is a packaging anti-pattern for published packages: a resolver that cannot satisfy the cap **backtracks to an older release** of the package rather than failing cleanly, so a consumer on a newer Python silently gets a stale version instead of a clear "not supported yet" error. See [ADR-0053](../../../finecode_internal_docs/adr/0053-derived-interpreter-axis-is-materialized-into-config.md) for the full rationale.
+
+The cap also has no remaining job now that the interpreter matrix exists. The set of Python versions an action is tested against is **derived from `requires-python` and bounded by what the provisioning toolchain (uv) can actually obtain** (ADR-0053, part 5), not by a hand-written ceiling. So removing the upper bound does not widen the test matrix to unreleased versions — the obtainable-versions ceiling does that job, on the developer's clock and in a reviewable diff.
+
+If a genuinely newer Python breaks a package, fix it when that version exists — do not pre-emptively cap. New packages must follow this: declare `requires-python = ">=<min>"` with no upper component.
+
 ## JSON-RPC key naming convention
 
 All JSON-RPC channels in FineCode use **camelCase** for message keys:

docs/reference/actions.md

@@ -265,6 +265,129 @@ Install dependencies into a specific environment.
 
 ---
 
+## `sync_toolchains`
+
+Derive each environment's toolchain axis from the project's declared support range and write it into the project definition file.
+
+- **Source:** `fine_envs.SyncToolchainsAction`
+
+**Payload fields:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `project_def_path` | `Path \| None` | `None` | Project definition file declaring the envs. `None` means the current project. |
+| `save` | `bool` | `True` | Write the derived axis to the file. `False` derives and reports without writing. |
+
+**Result fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `axes` | `list[EnvToolchainAxis]` | Per env: `declared`, `derived`, and whether it `changed` |
+| `saved` | `bool` | Whether a derived axis was written |
+
+A **toolchain** is the implementation-and-version a project is executed against; in Python it is an [interpreter](../glossary.md#interpreter). Every ecosystem declares its support range somewhere (`requires-python`, `engines`, `required_ruby_version`), and a language handler expands that range into toolchain identities. The action dispatches on project language to the matching subaction.
+
+The axis is *materialized* — written to the file rather than recomputed on each run — so that config resolution stays a pure read of already-declared data. See [ADR-0053](../adr/0053-derived-interpreter-axis-is-materialized-into-config.md) for why, and note the consequence: the axis is wholly generated, so extra toolchains are configured as *inputs to the source* (`extra_interpreters`) rather than hand-added to its output.
+
+---
+
+## `check_toolchains`
+
+Check whether each environment's materialized toolchain axis still matches what the source derives. Fails with a non-zero return code on drift.
+
+- **Source:** `fine_envs.CheckToolchainsAction`
+
+**Payload fields:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `project_def_path` | `Path \| None` | `None` | Project definition file declaring the envs. `None` means the current project. |
+
+**Result fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `stale_axes` | `list[EnvToolchainAxis]` | Envs whose declared axis differs from the derived one |
+
+A generated, committed axis can go stale — the support range changes, or the source learns about a newer toolchain. That is the same staleness a lock file has, and it is caught the same way: re-derive and compare. Wire this into `precommit` and CI. Runs `sync_toolchains` with `save = False` and reports what would change.
+
+---
+
+## `sync_python_interpreters`
+
+Derive an environment's Python interpreter axis from `requires-python`. Language-specific subaction of `sync_toolchains`.
+
+- **Source:** `fine_python_lang.SyncPythonInterpretersAction`
+- **Handler:** `fine_python_package_info.SyncPythonInterpretersPyHandler`
+- **Preset:** `fine_python_envs`
+
+**Payload fields:** same as `sync_toolchains`. **Result fields:** same as `sync_toolchains`.
+
+**Handler config:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `envs` | `list[str]` | `[]` | Envs whose interpreter axis is derived. Empty means none — the action is a no-op. An env either derives its axis or has one pinned, never both. |
+| `max_supported_python` | `str \| None` | `None` | Cap the newest CPython to derive. `None` means no cap beyond what is obtainable. |
+| `extra_interpreters` | `list[str]` | `[]` | Interpreters beyond the derived CPython rows, e.g. `["pypy@3.11"]`. |
+
+`requires-python` is a *specifier*, not an enumeration, so it is expanded against the set of **obtainable** interpreters (see `list_obtainable_toolchains` below). An open upper bound (`>=3.11`) — the correct form for a published package — is bounded by that set rather than rejected. The result therefore depends on something outside the specifier, which is exactly why it is persisted.
+
+`requires-python` constrains version only and carries no implementation, so the derived axis is CPython-only. PyPy and friends are configured via `extra_interpreters`.
+
+Matrices stay opt-in: with no `envs` configured, nothing is derived and every action keeps running in a single environment with an unchanged result shape.
+
+The derived axis is written into the **project's own** definition file, and project config beats preset config. So if a preset pins `interpreters` for an env that is also listed in `envs`, the derived axis is materialized over it and the run warns once, since the pin stops having any effect. To keep the preset's axis instead, drop that env from `envs` in your own config. Deriving into your own file is also the only way to override a pinned axis at all, because config layering can replace a key but never unset one.
+
+Materializing once per project rather than sharing one axis from a preset is deliberate: the axis derives from `requires-python`, which is per-project, and a project that states its own axis cannot have its matrix changed by a preset bump without a diff. See [ADR-0053](../adr/0053-derived-interpreter-axis-is-materialized-into-config.md) and `SyncPythonInterpretersPyHandler`'s docstring.
+
+---
+
+## `list_obtainable_toolchains`
+
+List the toolchains the environment provisioner is able to obtain.
+
+- **Source:** `fine_envs.ListObtainableToolchainsAction`
+
+**Payload fields:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `include_prereleases` | `bool` | `False` | Include prerelease toolchains (e.g. a Python beta). |
+
+**Result fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `toolchains` | `list[str]` | Canonical identities, e.g. `cpython@3.13` — no patch level, variant, or platform tag |
+
+**"Obtainable" is deliberately not "installed".** This reports what the *provisioner* can get — a property of a locked dependency — not what happens to be present on this machine. Only the former may feed a derived matrix axis: an axis sourced from local installs would differ between developers on the same commit. Whether a toolchain is available *here* is a separate question, and would be a separate action.
+
+The provisioner is the authority because deriving a version it cannot obtain yields an axis whose environments cannot be created. This is what `sync_toolchains` expands `requires-python` against.
+
+---
+
+## `list_obtainable_python_interpreters`
+
+Language-specific subaction of `list_obtainable_toolchains`. Backed by uv.
+
+- **Source:** `fine_python_lang.ListObtainablePythonInterpretersAction`
+- **Handler:** `fine_python_uv.UvListObtainablePythonInterpretersHandler`
+- **Preset:** `fine_python_envs`
+
+**Payload and result fields:** same as `list_obtainable_toolchains`.
+
+**Handler config:**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `str` | `"default"` | Build variant to report. `freethreaded` builds are a separate variant the `(implementation, version)` identity cannot express. |
+
+Runs `uv python list --only-downloads`, which reports uv's own manifest rather than the machine's installed Pythons. uv's listing is far finer-grained than a matrix axis — patch levels, prereleases, freethreaded variants, platform tags — and all of that is collapsed to one identity per implementation and minor version. Prereleases are excluded by default, so a released beta (`cpython-3.15.0b1`) never enters an axis.
+
+---
+
+
 ## `dump_config`
 
 Dump the resolved configuration for a source artifact that includes FineCode configuration.

extensions/fine_python_lang/fine_python_lang/__init__.py

@@ -23,6 +23,16 @@
     LockPythonDependenciesRunContext,
     LockPythonDependenciesRunPayload,
 )
+from fine_python_lang.list_obtainable_python_interpreters_action import (
+    ListObtainablePythonInterpretersAction,
+    ListObtainablePythonInterpretersRunContext,
+    ListObtainablePythonInterpretersRunPayload,
+)
+from fine_python_lang.sync_python_interpreters_action import (
+    SyncPythonInterpretersAction,
+    SyncPythonInterpretersRunContext,
+    SyncPythonInterpretersRunPayload,
+)
 from fine_python_lang.text_document_prepare_call_hierarchy_python_action import (
     TextDocumentPrepareCallHierarchyPythonAction,
 )
@@ -74,6 +84,12 @@
     "LockPythonDependenciesAction",
     "LockPythonDependenciesRunContext",
     "LockPythonDependenciesRunPayload",
+    "ListObtainablePythonInterpretersAction",
+    "ListObtainablePythonInterpretersRunContext",
+    "ListObtainablePythonInterpretersRunPayload",
+    "SyncPythonInterpretersAction",
+    "SyncPythonInterpretersRunContext",
+    "SyncPythonInterpretersRunPayload",
     "TextDocumentHoverPythonAction",
     "TextDocumentDefinitionPythonAction",
     "TextDocumentReferencesPythonAction",

extensions/fine_python_lang/fine_python_lang/list_obtainable_python_interpreters_action.py

@@ -0,0 +1,40 @@
+# docs: docs/reference/actions.md
+import dataclasses
+
+from finecode_extension_api import code_action
+from fine_envs.list_obtainable_toolchains_action import (
+    ListObtainableToolchainsAction,
+    ListObtainableToolchainsRunPayload,
+    ListObtainableToolchainsRunResult,
+)
+
+
+@dataclasses.dataclass
+class ListObtainablePythonInterpretersRunPayload(ListObtainableToolchainsRunPayload):
+    """Same payload as the parent."""
+
+
+class ListObtainablePythonInterpretersRunContext(
+    code_action.RunActionContext[ListObtainablePythonInterpretersRunPayload]
+): ...
+
+
+class ListObtainablePythonInterpretersAction(
+    code_action.Action[
+        ListObtainablePythonInterpretersRunPayload,
+        ListObtainablePythonInterpretersRunContext,
+        ListObtainableToolchainsRunResult,
+    ]
+):
+    """List the Python interpreters the environment provisioner can obtain.
+
+    Returns canonical ``<implementation>@<minor version>`` identities across every
+    implementation the provisioner offers, stable releases only by default.
+    """
+
+    DESCRIPTION = "List the Python interpreters the environment provisioner can obtain."
+    PAYLOAD_TYPE = ListObtainablePythonInterpretersRunPayload
+    RUN_CONTEXT_TYPE = ListObtainablePythonInterpretersRunContext
+    RESULT_TYPE = ListObtainableToolchainsRunResult
+    LANGUAGE = "python"
+    PARENT_ACTION = ListObtainableToolchainsAction

extensions/fine_python_lang/fine_python_lang/sync_python_interpreters_action.py

@@ -0,0 +1,50 @@
+# docs: docs/reference/actions.md
+import dataclasses
+
+from finecode_extension_api import code_action
+from fine_envs.sync_toolchains_action import (
+    SyncToolchainsAction,
+    SyncToolchainsRunPayload,
+    SyncToolchainsRunResult,
+)
+
+
+@dataclasses.dataclass
+class SyncPythonInterpretersRunPayload(SyncToolchainsRunPayload):
+    """Same payload as the parent.
+
+    The Python source takes no extra caller-facing parameters: which envs derive an
+    axis, and how the derivation is tuned, is derivation intent and lives in handler
+    config (ADR-0053).
+    """
+
+
+class SyncPythonInterpretersRunContext(
+    code_action.RunActionContext[SyncPythonInterpretersRunPayload]
+): ...
+
+
+class SyncPythonInterpretersAction(
+    code_action.Action[
+        SyncPythonInterpretersRunPayload,
+        SyncPythonInterpretersRunContext,
+        SyncToolchainsRunResult,
+    ]
+):
+    """Derive an env's Python interpreter axis.
+
+    The Python materialization of ``sync_toolchains``: a toolchain here is an
+    interpreter, identified by implementation and version together (``cpython@3.12``).
+
+    Where the supported versions are declared, and how they expand into identities, is
+    the handler's business.
+    """
+
+    DESCRIPTION = (
+        "Derive an env's Python interpreter axis from the project's declared support."
+    )
+    PAYLOAD_TYPE = SyncPythonInterpretersRunPayload
+    RUN_CONTEXT_TYPE = SyncPythonInterpretersRunContext
+    RESULT_TYPE = SyncToolchainsRunResult
+    LANGUAGE = "python"
+    PARENT_ACTION = SyncToolchainsAction

extensions/fine_python_lang/pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "fine_check_imports~=0.1.0a0",
     "fine_semantic_tokens~=0.1.0a0",
     "fine_inlay_hints~=0.1.0a0",
+    "fine_envs~=0.1.0a0",
 ]
 
 [dependency-groups]

extensions/fine_python_package_info/fine_python_package_info/__init__.py

@@ -9,9 +9,11 @@
 from .publish_artifact_to_registry_py_handler import \
     PublishArtifactToRegistryPyHandler
 from .py_package_layout_info_provider import PyPackageLayoutInfoProvider
+from .sync_python_interpreters_handler import SyncPythonInterpretersHandler
 
 __all__ = [
     "BuildArtifactPyHandler",
+    "SyncPythonInterpretersHandler",
     "GetDistArtifactVersionPyHandler",
     "PyPackageLayoutInfoProvider",
     "GetSrcArtifactVersionPyHandler",