chtypes 0.3.1__tar.gz → 0.3.2__tar.gz

{chtypes-0.3.1 → chtypes-0.3.2}/CHANGELOG.md

@@ -6,6 +6,23 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+## [0.3.2] — 2026-09-28
+
+Speaks ABI revision 5, unchanged from 0.3.1: every artifact 0.3.1 loads, this release loads.
+
+### Added
+
+- **`ReleaseEntry.abi_revision`** (`int | None`): the row's `abi_revision`, `None` when the row declares none or declares something that is not an integer.
+
+### Changed
+
+- **Installs move to a per-revision directory, so the first fetch after upgrading downloads again.** The per-user cache `default_registry_dir()` is now `${XDG_CACHE_HOME:-~/.cache}/chtypes/artifacts/abi<R>/<os>-<arch>`, `<R>` this binding's own `ABI_REVISION`, where it was `…/chtypes/artifacts/<os>-<arch>`. Two SDK versions that speak different ABI revisions on one machine no longer overwrite each other's artifacts. Nothing is migrated: the old directory is simply no longer read, and can be deleted once nothing older uses it. `CHTYPES_REGISTRY` and an explicit directory are taken exactly as before.
+- **Fetch now selects only artifacts built at this binding's own ABI revision** (`docs/guides/fetch.md` §2). The release's rows are narrowed to those whose `abi_revision` is `ABI_REVISION` before the newest-version, highest-build rule applies; a row that declares no revision never matches. Nothing at that revision for the line and platform is `ArtifactUnpublishedError` (`CHTYPES_ARTIFACT_UNPUBLISHED`, exit 4), naming the revision(s) the release does serve — never a fallback to another revision's build, which the loader would refuse anyway. Across a revision cutover the grace this gives an older binding is temporary: an older-revision build stays fetchable only until that line's next publish evicts it under retention, which keeps two builds per version.
+- **`fetch_lines(..., all_lines=True)` and `python -m chtypes fetch --all` no longer skip a line silently.** A line the release has for the platform only at another ABI revision, or only in rows that record none (built before revisions were recorded), is not installed, and one loud warning line (through `progress` when one is given, else on stderr) names the line, the platform, what the release does serve and this binding's revision; every other line still installs, and the exit status stays 0 when they all do.
+- **`list` shows only the release's rows at this binding's ABI revision** — what a fetch could install — and, when that hides any of the platform's rows, adds one line naming them: `<N> row(s) at ABI revision(s) <S> not shown; this SDK speaks <R>`, or, for rows that record none, `<M> row(s) that record no ABI revision (built before revisions were recorded) not shown; this SDK speaks <R>`. Nothing is added when nothing was hidden.
+- **On darwin-arm64, fetching line 24.8 now fails at fetch time** with `CHTYPES_ARTIFACT_UNPUBLISHED` (exit 4) instead of installing an artifact the loader then refuses: the release's only 24.8 rows for that platform record no ABI revision, because they were built before revisions were recorded, and the message says exactly that rather than that the release serves none.
+- `Release.offered()` now returns only rows at this binding's ABI revision, and `Release.select()` considers only those.
+
 ## [0.3.1] — 2026-09-26
 
 Speaks ABI revision 5, unchanged from 0.3.0: every artifact 0.3.0 loads, this release loads.

{chtypes-0.3.1 → chtypes-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI
 Project-URL: Homepage, https://github.com/wave-rf/chtypes
 Project-URL: Repository, https://github.com/wave-rf/chtypes
@@ -31,7 +31,7 @@ uv add chtypes            # or: pip install chtypes
 python -m chtypes fetch 25.8
 ```
 
-The fetch lands in `~/.cache/chtypes/artifacts/<os>-<arch>/25.8/` — the per-user cache every chtypes binding reads by default — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
+The fetch lands in `~/.cache/chtypes/artifacts/abi<R>/<os>-<arch>/25.8/` — the per-user cache every chtypes binding reads by default, `<R>` the ABI revision this SDK speaks (fetch installs only artifacts built at it) — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
 
 ## Quickstart
 

{chtypes-0.3.1 → chtypes-0.3.2}/README.md

@@ -13,7 +13,7 @@ uv add chtypes            # or: pip install chtypes
 python -m chtypes fetch 25.8
 ```
 
-The fetch lands in `~/.cache/chtypes/artifacts/<os>-<arch>/25.8/` — the per-user cache every chtypes binding reads by default — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
+The fetch lands in `~/.cache/chtypes/artifacts/abi<R>/<os>-<arch>/25.8/` — the per-user cache every chtypes binding reads by default, `<R>` the ABI revision this SDK speaks (fetch installs only artifacts built at it) — after checking an ed25519 signature over the release and the sha256 of every byte. `$CHTYPES_REGISTRY` overrides it. The ed25519 verifier is pure stdlib too.
 
 ## Quickstart
 

{chtypes-0.3.1 → chtypes-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "0.3.1"
+version = "0.3.2"
 description = "Python binding for the chtypes artifacts: ClickHouse's own type system, per version, behind the frozen chs_* C ABI"
 readme = "README.md"
 license = "Apache-2.0"

{chtypes-0.3.1 → chtypes-0.3.2}/src/chtypes/__main__.py

@@ -196,7 +196,14 @@ def _cmd_verify(args: argparse.Namespace) -> int:
 
 
 def _cmd_list(args: argparse.Namespace) -> int:
-    from .fetch import Fetcher, fetch_destination, host_platform, installed_lines
+    from .fetch import (
+        Fetcher,
+        _fetch_abi_revision,
+        _not_shown,
+        fetch_destination,
+        host_platform,
+        installed_lines,
+    )
 
     platform = args.platform or host_platform()
     registry = fetch_destination(args.dest, platform=platform)
@@ -221,6 +228,11 @@ def _cmd_list(args: argparse.Namespace) -> int:
             f"  {entry.minor:<8} {entry.clickhouse_version:<18} b{entry.build_number:<3} "
             f"{entry.file}  [{state}]\n"
         )
+    # Only this SDK's own ABI revision is offered (docs/guides/fetch.md §2), and
+    # one line names what that hid.
+    note = _not_shown([e for e in release.entries if e.platform == platform], _fetch_abi_revision())
+    if note is not None:
+        sys.stdout.write(f"  {note}\n")
     sys.stdout.flush()
     return EXIT_OK
 

{chtypes-0.3.1 → chtypes-0.3.2}/src/chtypes/_manifest.py

@@ -15,6 +15,7 @@ import platform as _platform
 from dataclasses import dataclass, fields
 from pathlib import Path
 
+from ._native import ABI_REVISION
 from .errors import RegistryError
 
 __all__ = [
@@ -38,11 +39,15 @@ def host_platform() -> str:
 
 def cache_registry_dir(platform: str | None = None) -> str:
     """The per-user artifact cache for a platform — ``${XDG_CACHE_HOME:-~/.cache}/
-    chtypes/artifacts/<os>-<arch>``, this host's by default. Where fetch installs,
-    where a core-repository build lands, and slot 3 of the registry search path
-    (docs/guides/fetch.md §1). A path, not a promise: it need not exist yet."""
+    chtypes/artifacts/abi<R>/<os>-<arch>``, R this binding's `ABI_REVISION`, this
+    host's platform by default. Where fetch installs, and slot 3 of the registry
+    search path (docs/guides/fetch.md §1); keyed by revision so two SDK versions
+    at different revisions never share it. A path, not a promise: it need not
+    exist yet."""
     base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
-    return os.path.join(base, "chtypes", "artifacts", platform or host_platform())
+    return os.path.join(
+        base, "chtypes", "artifacts", f"abi{ABI_REVISION}", platform or host_platform()
+    )
 
 
 @dataclass(frozen=True, slots=True)

{chtypes-0.3.1 → chtypes-0.3.2}/src/chtypes/fetch.py

@@ -30,6 +30,7 @@ import logging
 import os
 import re
 import shutil
+import sys
 import tarfile
 import tempfile
 import time
@@ -51,6 +52,7 @@ from ._manifest import (
     read_manifest,
     verify_library,
 )
+from ._native import ABI_REVISION
 from .errors import (
     ArtifactCorruptError,
     ArtifactPinnedError,
@@ -145,6 +147,90 @@ def _env_flag(name: str) -> bool:
     return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
 
 
+#: TEST-ONLY. When set, the ABI revision fetch selects release rows at, in place
+#: of `ABI_REVISION` (docs/guides/fetch.md §2). Not part of the public contract:
+#: the fetch-fixture suites set it to the revision their fixture release carries
+#: — derived from that release's own ``index.json`` — so a binding whose own
+#: revision has moved ahead of the fixtures still exercises the whole chain.
+#: It changes WHICH rows are eligible and nothing else: the default registry
+#: directory stays ``abi<ABI_REVISION>/``, and the loader still refuses an
+#: artifact of another revision.
+_ABI_REVISION_OVERRIDE: int | None = None
+
+
+def _fetch_abi_revision() -> int:
+    """The one ABI revision whose rows fetch may install: this binding's own."""
+    return ABI_REVISION if _ABI_REVISION_OVERRIDE is None else _ABI_REVISION_OVERRIDE
+
+
+def _revision_of(value: object) -> int | None:
+    """A row's ``abi_revision`` when it is a JSON integer, else None. The artifact
+    producer writes the field from the revision that introduced it onward, so a
+    row without one is an older revision; a value that is not an integer is
+    read the same way rather than failing the whole listing."""
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+#: Rows that carry no ``abi_revision``, named with the reason: the artifact
+#: producer records the field from the revision that introduced it onward. Every
+#: unpublished message, ``--all`` warning and ``list`` note says this in these
+#: words rather than that the release serves "none".
+_BUILT_BEFORE: Final = "(built before revisions were recorded)"
+_NO_RECORDED_REVISION: Final = f"rows that record no ABI revision {_BUILT_BEFORE}"
+
+
+def _served(entries: Sequence[ReleaseEntry], noun: str) -> str:
+    """What the release DOES have for ``noun``, for an unpublished message: the
+    ABI revision(s) its rows carry, or that it has none at any revision."""
+    if not entries:
+        return f"the release does not have {noun} at any ABI revision"
+    revs = sorted({e.abi_revision for e in entries if e.abi_revision is not None})
+    if not revs:
+        return f"the release has {noun} only in {_NO_RECORDED_REVISION}"
+    said = (
+        f"ABI revision {revs[0]}"
+        if len(revs) == 1
+        else "ABI revisions " + ", ".join(str(r) for r in revs)
+    )
+    if any(e.abi_revision is None for e in entries):
+        said += f" and in {_NO_RECORDED_REVISION}"
+    return f"the release has {noun} only at {said}"
+
+
+def _skipped_lines(on_platform: Sequence[ReleaseEntry], platform: str, rev: int) -> list[str]:
+    """One message per line the release has for ``platform`` only at another ABI
+    revision, or only in rows that record none — the lines ``--all`` installs
+    nothing for — in numeric line order."""
+    by_line: dict[str, list[ReleaseEntry]] = {}
+    for e in on_platform:
+        by_line.setdefault(e.minor, []).append(e)
+    return [
+        f"ClickHouse line {line} on {platform} is not installed: "
+        f"{_served(rows, f'that line for {platform}')}, and this SDK speaks ABI revision {rev}"
+        for line, rows in sorted(by_line.items(), key=lambda kv: _minor_key(kv[0]))
+        if not any(e.abi_revision == rev for e in rows)
+    ]
+
+
+def _not_shown(on_platform: Sequence[ReleaseEntry], rev: int) -> str | None:
+    """``list``'s one line naming the platform's rows at another ABI revision,
+    which it does not show (docs/guides/fetch.md §6); None when none were
+    hidden. Rows that carry no ``abi_revision`` are named for what they are —
+    built before revisions were recorded — never as a revision called "none"."""
+    hidden = [e for e in on_platform if e.abi_revision != rev]
+    if not hidden:
+        return None
+    declared = [e.abi_revision for e in hidden if e.abi_revision is not None]
+    undeclared = len(hidden) - len(declared)
+    parts = []
+    if declared:
+        revs = ", ".join(str(r) for r in sorted(set(declared)))
+        parts.append(f"{len(declared)} row(s) at ABI revision(s) {revs}")
+    if undeclared:
+        parts.append(f"{undeclared} row(s) that record no ABI revision " + _BUILT_BEFORE)
+    return f"{' and '.join(parts)} not shown; this SDK speaks {rev}"
+
+
 # ------------------------------------------------------------------ §1 paths
 
 
@@ -372,6 +458,11 @@ class ReleaseEntry:
     build: int = 0
     #: The core commit the wrapper was built from; ``""`` on an old row.
     core_commit: str = ""
+    #: The chs_* ABI revision the artifact was built from, or None when the row
+    #: declares none (or declares something that is not an integer). Fetch
+    #: installs only a row at this binding's own `ABI_REVISION`
+    #: (docs/guides/fetch.md §2): any other would be refused at load.
+    abi_revision: int | None = None
 
     @property
     def platform(self) -> str:
@@ -411,10 +502,14 @@ class Release:
     license_url: str = ""
 
     def offered(self, platform: str) -> list[ReleaseEntry]:
-        """Every line published for a platform, newest patch per line, release order."""
+        """Every line published for a platform at this binding's ABI revision,
+        newest patch per line (then highest build), release order. Rows of any
+        other revision, and rows that record none, are not offered: fetch never
+        installs them (docs/guides/fetch.md §2)."""
+        rev = _fetch_abi_revision()
         best: dict[str, ReleaseEntry] = {}
         for e in self.entries:
-            if e.platform != platform:
+            if e.platform != platform or e.abi_revision != rev:
                 continue
             cur = best.get(e.minor)
             if cur is None or e.rank > cur.rank:
@@ -426,42 +521,49 @@ class Release:
 
     def select(self, spelling: str, platform: str) -> ReleaseEntry:
         """A line (``25.8``) resolves to the one patch published for it; an
-        exact patch (``25.8.28.1-lts``) is a hard requirement (§2)."""
+        exact patch (``25.8.28.1-lts``) is a hard requirement (§2). Either way,
+        only rows at this binding's ABI revision are considered, FIRST: nothing
+        at that revision is `ArtifactUnpublishedError`, never another
+        revision's row."""
         line, exact = parse_spelling(spelling)
-        offered = self.offered(platform)
-        if not offered:
+        rev = _fetch_abi_revision()
+        on_platform = [e for e in self.entries if e.platform == platform]
+        if not on_platform:
             raise ArtifactUnpublishedError(
                 f"chtypes: {self.source} publishes nothing for {platform} "
                 f"(it has: {', '.join(self.platforms()) or 'nothing'})"
             )
+        have = ", ".join(e.clickhouse_version for e in on_platform if e.abi_revision == rev)
         if exact is not None:
             bare = exact.split("-", 1)[0]
             # A rebuild publishes the same clickhouse_version twice, so an exact
             # request can match more than one row: take the highest build, never
             # whichever the index happens to list first.
-            hits = [
+            any_revision = [
                 e
-                for e in self.entries
-                if e.platform == platform
-                and (
-                    e.clickhouse_version == exact
-                    or ("-" not in exact and e.clickhouse_version.split("-", 1)[0] == bare)
-                )
+                for e in on_platform
+                if e.clickhouse_version == exact
+                or ("-" not in exact and e.clickhouse_version.split("-", 1)[0] == bare)
             ]
+            hits = [e for e in any_revision if e.abi_revision == rev]
             if hits:
                 return max(hits, key=lambda e: e.rank)
             raise ArtifactUnpublishedError(
-                f"chtypes: you asked for exactly ClickHouse {exact} on {platform} and "
-                f"{self.source} does not publish it (it has: "
-                f"{', '.join(e.clickhouse_version for e in offered)}). "
+                f"chtypes: you asked for exactly ClickHouse {exact} on {platform} at ABI "
+                f"revision {rev} (this SDK's) and {self.source} does not publish it at that "
+                f"revision: {_served(any_revision, f'that patch for {platform}')}; at ABI "
+                f"revision {rev} the release has: {have or 'nothing'}. "
                 f"Ask for the line ({line}) to take what was published."
             )
-        for e in offered:
+        for e in self.offered(platform):
             if e.minor == line:
                 return e
+        any_revision = [e for e in on_platform if e.minor == line]
         raise ArtifactUnpublishedError(
-            f"chtypes: no artifact for ClickHouse line {line} on {platform} at {self.source} "
-            f"(it has: {', '.join(e.clickhouse_version for e in offered)})"
+            f"chtypes: no artifact for ClickHouse line {line} on {platform} at ABI revision "
+            f"{rev} (this SDK's) at {self.source}: "
+            f"{_served(any_revision, f'that line for {platform}')}"
+            f"; at ABI revision {rev} the release has: {have or 'nothing'}"
         )
 
 
@@ -509,6 +611,7 @@ def _parse_index(raw: bytes, source: str) -> tuple[list[ReleaseEntry], str, str,
                     arch=str(row["arch"]),
                     build=int(row.get("build") or 0),
                     core_commit=str(row.get("core_commit") or ""),
+                    abi_revision=_revision_of(row.get("abi_revision")),
                 )
             )
         except (KeyError, TypeError, ValueError) as exc:
@@ -725,6 +828,7 @@ class Fetcher:
         host = (os.environ.get(ENV_ARTIFACTS_URL) or DEFAULT_ARTIFACTS_URL).rstrip("/")
         base = url or f"{host}/{self.tag}"
         self.progress: Progress = progress or (lambda line: None)
+        self._progress_given = progress is not None
         self.source = _Source(base, self._say)
         self.lock = Path(lock) if lock is not None else None
         self.frozen = frozen
@@ -743,6 +847,19 @@ class Fetcher:
         log.info("%s", line)
         self.progress(line)
 
+    def _warn(self, message: str) -> None:
+        """A loud line, never silent: through ``progress`` when the caller gave
+        one (the CLI does), else straight to stderr."""
+        line = f"chtypes: WARNING: {message}"
+        # Not log.warning: logging's last-resort handler would print it a
+        # second time on stderr for a process that configured no logging.
+        log.info("%s", line)
+        if self._progress_given:
+            self.progress(line)
+        else:
+            sys.stderr.write(line + "\n")
+            sys.stderr.flush()
+
     def _lock_pins(self) -> dict[str, dict[str, str]]:
         if self._pins is None:
             if self.lock is None:
@@ -926,12 +1043,21 @@ class Fetcher:
         return installed
 
     def ensure_all(self) -> list[Path]:
-        """Every line the release publishes for the platform."""
-        offered = self.release().offered(self.platform)
+        """Every line the release publishes for the platform at this binding's
+        ABI revision. A line it has only at another revision is not installed,
+        and is named in one loud warning line; the rest go on."""
+        release = self.release()
+        offered = release.offered(self.platform)
+        rev = _fetch_abi_revision()
+        on_platform = [e for e in release.entries if e.platform == self.platform]
         if not offered:
             raise ArtifactUnpublishedError(
-                f"chtypes: {self.release().source} publishes nothing for {self.platform}"
+                f"chtypes: {release.source} publishes nothing for {self.platform} at ABI "
+                f"revision {rev} (this SDK's): "
+                f"{_served(on_platform, f'rows for {self.platform}')}"
             )
+        for message in _skipped_lines(on_platform, self.platform, rev):
+            self._warn(message)
         out = [self.install(entry) for entry in offered]
         self.install_goldens()
         return out

{chtypes-0.3.1 → chtypes-0.3.2}/src/chtypes/registry.py

@@ -76,10 +76,10 @@ ENV_REGISTRY: Final = "CHTYPES_REGISTRY"
 
 def default_registry_dir() -> str:
     """The per-user artifact cache for this host — ``${XDG_CACHE_HOME:-~/.cache}/
-    chtypes/artifacts/<os>-<arch>`` with ``<arch>`` spelled the artifact way
-    (``amd64``/``arm64``). Where ``chtypes fetch`` installs, where a core-repo
-    build lands, and slot 3 of the registry search path every SDK walks
-    (docs/guides/fetch.md §1). A path, not a promise: it need not exist yet."""
+    chtypes/artifacts/abi<R>/<os>-<arch>`` with R this binding's `ABI_REVISION`
+    and ``<arch>`` spelled the artifact way (``amd64``/``arm64``). Where
+    ``chtypes fetch`` installs, and slot 3 of the registry search path every SDK
+    walks (docs/guides/fetch.md §1). A path, not a promise: it need not exist yet."""
     return cache_registry_dir()
 
 

{chtypes-0.3.1 → chtypes-0.3.2}/tests/conftest.py

@@ -6,14 +6,15 @@ server-truth suites against this same tree.
 
 The registry comes from the search path (docs/guides/fetch.md §1): `$CHTYPES_REGISTRY`,
 else the per-user artifact cache for this host (`chtypes.default_registry_dir()`:
-`~/.cache/chtypes/artifacts/<os>-<arch>`, where `chtypes fetch` installs and a
-core-repo build lands), else the system locations. Without a single line on it
+`~/.cache/chtypes/artifacts/abi<R>/<os>-<arch>`, R the binding's ABI revision,
+where `chtypes fetch` installs), else the system locations. Without a single line on it
 the suite skips with that message: a green run that never touched a ClickHouse
 build would be worse than no run.
 """
 
 from __future__ import annotations
 
+import json
 import os
 from collections.abc import Callable
 from pathlib import Path
@@ -23,6 +24,47 @@ import pytest
 import chtypes
 
 FALLBACK_REGISTRY = Path(chtypes.default_registry_dir())
+FETCH_FIXTURES = Path(__file__).resolve().parents[2] / "tests" / "fixtures" / "fetch"
+
+
+def _fixture_abi_revision(fixtures: Path) -> int:
+    """The ABI revision the fixture set under ``fixtures`` DECLARES, as
+    ``expected.json``'s ``fixtures_abi_revision``: the revision every fixture's
+    rows carry except ``two-revisions/``'s, which deliberately spans two.
+
+    Read from the fixtures' own declaration, never typed into a test: a suite
+    that hand-set it would be testing its author's belief about the fixtures,
+    not the fetch. A missing or non-integer field raises."""
+    expected = fixtures / "expected.json"
+    doc = json.loads(expected.read_text())
+    if "fixtures_abi_revision" not in doc:
+        raise AssertionError(
+            f"{expected} declares no fixtures_abi_revision — regenerate the fixtures from the "
+            f"artifact producer's current set"
+        )
+    rev = doc["fixtures_abi_revision"]
+    if not isinstance(rev, int) or isinstance(rev, bool):
+        raise AssertionError(f"{expected}: fixtures_abi_revision is {rev!r}, not an integer")
+    return rev
+
+
+@pytest.fixture
+def derive_fixture_abi_revision() -> Callable[[Path], int]:
+    """The declared-field reader itself, for the test that pins it."""
+    return _fixture_abi_revision
+
+
+@pytest.fixture
+def at_fixture_revision(monkeypatch: pytest.MonkeyPatch) -> int:
+    """Fetch selects only rows at the binding's own ABI revision
+    (docs/guides/fetch.md §2); the fixtures carry whatever revision they were
+    generated at, and declare it. Point the test-only override at THAT revision —
+    read from expected.json's ``fixtures_abi_revision`` — for this test, and return it."""
+    from chtypes import fetch as fetch_module
+
+    rev = _fixture_abi_revision(FETCH_FIXTURES)
+    monkeypatch.setattr(fetch_module, "_ABI_REVISION_OVERRIDE", rev)
+    return rev
 
 
 def _candidate() -> tuple[Path, str]:

{chtypes-0.3.1 → chtypes-0.3.2}/tests/test_cli.py

@@ -35,12 +35,26 @@ def _keys() -> str:
 
 
 @pytest.fixture
-def env(isolated_search_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+def env(
+    isolated_search_path: Path, monkeypatch: pytest.MonkeyPatch, request: pytest.FixtureRequest
+) -> Path:
     if EXPECTED_FILE.is_file():
         monkeypatch.setenv("CHTYPES_TRUSTED_KEYS", _keys())
+        # Fetch at the ABI revision the fixtures carry, read off their own rows.
+        request.getfixturevalue("at_fixture_revision")
     return isolated_search_path
 
 
+# `python -m chtypes`, exactly — runpy runs chtypes/__main__.py as __main__,
+# which is all `-m` does — with fetch's test-only revision override set first
+# (the child cannot inherit the parent's monkeypatch). argv[1] is the revision.
+_MODULE_AT_REVISION = (
+    "import runpy, sys; import chtypes.fetch as f; "
+    "f._ABI_REVISION_OVERRIDE = int(sys.argv.pop(1)); "
+    "runpy.run_module('chtypes', run_name='__main__', alter_sys=True)"
+)
+
+
 def test_where_prints_the_write_directory(env: Path, capsys: pytest.CaptureFixture[str]) -> None:
     assert main(["where"]) == 0
     out = capsys.readouterr().out
@@ -80,7 +94,11 @@ def test_usage_errors_exit_2(env: Path, capsys: pytest.CaptureFixture[str]) -> N
     ),
 )
 def test_fetch_exit_codes_and_streams(
-    verdict: dict, env: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    verdict: dict,
+    env: Path,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    at_fixture_revision: int,
 ) -> None:
     """Every fixture verdict through the real entry point, in a subprocess:
     the spec's exit code, the code on stderr, and stdout empty or exactly
@@ -99,8 +117,9 @@ def test_fetch_exit_codes_and_streams(
     proc = subprocess.run(
         [
             sys.executable,
-            "-m",
-            "chtypes",
+            "-c",
+            _MODULE_AT_REVISION,
+            str(at_fixture_revision),
             "fetch",
             "25.8",
             "--platform",
@@ -174,6 +193,19 @@ def test_verify_and_list(env: Path, tmp_path: Path, capsys: pytest.CaptureFixtur
     out = capsys.readouterr().out
     assert "installed (" in out and "[installed]" in out and "signed by key" in out
     assert "[not installed]" not in out
+    assert "not shown" not in out  # every row is at the revision fetch selects at
+
+    # One revision past the fixtures' own, list shows none of their rows and
+    # says so in one line naming what it hid (docs/guides/fetch.md §6).
+    from chtypes import fetch as fetch_module
+
+    rev = fetch_module._fetch_abi_revision()
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr(fetch_module, "_ABI_REVISION_OVERRIDE", rev + 1)
+        assert main(["list", "--platform", PLATFORM, "--url", signed, "--dest", str(dest)]) == 0
+    out = capsys.readouterr().out
+    assert f"  2 row(s) at ABI revision(s) {rev} not shown; this SDK speaks {rev + 1}\n" in out
+    assert "[installed]" not in out
 
     # Corrupt one library: verify says so, exits 1, and names the line.
     (dest / "26.7" / "libchtypes.so").write_bytes(b"corrupt")