chtypes 1.0.4__tar.gz → 2.0.0.dev0__tar.gz

{chtypes-1.0.4 → chtypes-2.0.0.dev0}/CHANGELOG.md

@@ -6,6 +6,21 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-10-06
+
+### Added
+
+- Strict cache mode, and one error code for a cache that cannot be used (#486). The new code, `CHTYPES_CACHE_UNUSABLE` (exit status 9), names the path that failed, a reason (`unreadable_root`, `not_a_directory`, `unreadable_entry`, `unacceptable_record`, `layout_0x` or `unwritable`) and the errno name: Go `*ArtifactError` with `Code` `CodeCacheUnusable` and `Path`, `Reason` and `OSError` (`errors.Is(err, ErrCacheUnusable)`), Python `CacheUnusableError` (`path`, `reason`, `os_error`), TypeScript `CacheUnusableError` (`path`, `reason`, `osError`), Rust `Error::CacheUnusable(CacheFault)`. Strict mode is opt-in: Go `FetchOptions.StrictCache`, Python `FetchOptions(strict_cache=True)`, TypeScript `strictCache: true`, Rust `FetchOptions::strict_cache`, `CHTYPES_CACHE_STRICT=1`, or `--strict` on every CLI command. Under it, an unreadable cache root or entry, a record with nothing to re-verify from, or a 0.x layout is that error, never "not installed" and never a fall-through to a system directory; `chtypes where --strict` checks the root before printing it, and `chtypes verify --strict` that verified nothing exits 1. The default mode answers as before, and now warns once per path it could not read. The rules are `docs/guides/fetch-v1.md` section 1, "The cache faults", and the `v1-cache-interop` job holds all four bindings to one answer for every fault, in both modes.
+
+### Changed
+
+- A write the fetch layer needed under the cache that failed is now `CHTYPES_CACHE_UNUSABLE` with reason `unwritable`, in every mode (#486). Go raised a `*UsageError` (CLI exit 2), Python a raw `OSError` (CLI exit 1), TypeScript a `UsageError` (CLI exit 2) and Rust `CHTYPES_SOURCE_UNREACHABLE` (exit 3), which a retry loop would retry. A cache root that cannot be read is now "not installed" with a warning in every binding and on every Python: Python before 3.14 raised a raw `PermissionError` there, and Rust `CHTYPES_SOURCE_UNREACHABLE`; strict mode makes it the new error.
+- Rust's default mode now treats an unreadable record, entry or `index.json` under the cache as absent, with a warning, where it used to report `CHTYPES_SOURCE_UNREACHABLE` (#486). Strict mode makes it `CHTYPES_CACHE_UNUSABLE` in all four.
+
+### Fixed
+
+- A cache one uid writes is readable by another, the cache and the system directories are one search, and a lookup writes nothing (#486). Go created every cache directory 0700 and every file 0600, and Python wrote `verified.json` and `index.json` 0600, so a cache fetched by one uid (a CI user) read as empty to another (a container's nonroot user). Now all four create every directory and file with mode 0777 or 0666 less the process umask, so at umask 022 another uid can read the cache, and readable is never writable. Lookups read the system directories differently: Go answered from the first root with a match, and TypeScript never read a system directory's installs at all. Now all four answer with the newest build across the cache and every system directory, a tie going to the cache, and `list` and `verify` read the same roots. Go, TypeScript and Rust created the layout (`oci-layout`, `blobs/`, `unpacked/`) on a lookup, `fetch --offline` included; now a lookup creates nothing, so a read-only mount reads cleanly. A `chtypes verify` that verified no build now says so on stderr, `verified 0 builds under <root>`, where it printed nothing and exited 0. A miss from a cache that is a 0.x registry directory names it and the v1 root, in the CLI and the registry alike. No name or signature changes. The rules are `docs/guides/fetch-v1.md` sections 1 and 6; every binding runs the `root-order-*` conformance cases, and the `v1-cache-interop` job reads every binding's cache as another uid.
+
 ## [1.0.4] — 2026-10-06
 
 ### Fixed

{chtypes-1.0.4 → chtypes-2.0.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 1.0.4
+Version: 2.0.0.dev0
 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
@@ -19,6 +19,8 @@ Description-Content-Type: text/markdown
 
 # chtypes — Python SDK
 
+> **2.0.0-dev: UNSTABLE, staging only, not for production.** This is the ABI v2 development binding (public issue #511). It speaks ABI v2's unstable description, pins its dev fingerprint and refuses a library with any other ("update your dev SDK"). It fetches only from the staging dev channel (`https://registry-staging.wavehouse.dev/chtypes/v2-dev`) and trusts only the staging key; `CHTYPES_ARTIFACTS_URL`, `CHTYPES_TRUSTED_KEYS` and `CHTYPES_ALLOW_UNSIGNED`, and the `bases`, `trusted_keys` and `allow_unsigned` fetch options, are ignored, each with one warning; `--lock`, `--frozen` and `--update`, and the `frozen`, `lock_path`, `lock_write` and `update` options, are refused, because a dev build is replaceable and a superseded one expires after 14 days. Its cache is `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`, or `<CHTYPES_CACHE>/v2-dev` under an explicit cache, which no 1.x SDK reads. Every vocabulary keeps a value it does not list as its `unknown(n)` member (`Outcome("x")`, whose `known` is `False`) instead of failing the document. The rules are r1 to r6 of [`docs/reference/abi-v2.md`](../docs/reference/abi-v2.md). For production, use the 1.x package: `pip install "chtypes<2"`.
+
 **If this row were inserted into this table on this ClickHouse version, what would happen?** chtypes answers with ClickHouse's own code: the real C++ type machinery, vendored per release into a native library behind the frozen `chs_*` C ABI and reached here through stdlib `ctypes`. Nothing semantic is reimplemented, so _"what does ClickHouse do with `256` into a `UInt8`?"_ is answered by ClickHouse rather than by a model of it. One peer binding among `{go, python, ts, rust}` — no language is privileged, and all four give one answer.
 
 Pure ctypes: no compiler, no build step. The only dependency is a zstd decompressor for the artifact layer, which is the standard library's own from Python 3.14 and the `backports.zstd` package before that.
@@ -28,9 +30,11 @@ Pure ctypes: no compiler, no build step. The only dependency is a zstd decompres
 Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime. The registry fetches the artifact on first use when autofetch is on (`Registry(autofetch=True)` or `CHTYPES_AUTOFETCH=1`), after verifying its signature and every byte against the signed statement; with autofetch off it answers only from what is already installed.
 
 ```sh
-uv add chtypes            # or: pip install chtypes
+uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 ```
 
+`uv add chtypes` and `pip install chtypes` never select a pre-release on their own: the specifier names a dev version, which is what allows one.
+
 ## Quickstart
 
 ```python

{chtypes-1.0.4 → chtypes-2.0.0.dev0}/README.md

@@ -1,5 +1,7 @@
 # chtypes — Python SDK
 
+> **2.0.0-dev: UNSTABLE, staging only, not for production.** This is the ABI v2 development binding (public issue #511). It speaks ABI v2's unstable description, pins its dev fingerprint and refuses a library with any other ("update your dev SDK"). It fetches only from the staging dev channel (`https://registry-staging.wavehouse.dev/chtypes/v2-dev`) and trusts only the staging key; `CHTYPES_ARTIFACTS_URL`, `CHTYPES_TRUSTED_KEYS` and `CHTYPES_ALLOW_UNSIGNED`, and the `bases`, `trusted_keys` and `allow_unsigned` fetch options, are ignored, each with one warning; `--lock`, `--frozen` and `--update`, and the `frozen`, `lock_path`, `lock_write` and `update` options, are refused, because a dev build is replaceable and a superseded one expires after 14 days. Its cache is `${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev`, or `<CHTYPES_CACHE>/v2-dev` under an explicit cache, which no 1.x SDK reads. Every vocabulary keeps a value it does not list as its `unknown(n)` member (`Outcome("x")`, whose `known` is `False`) instead of failing the document. The rules are r1 to r6 of [`docs/reference/abi-v2.md`](../docs/reference/abi-v2.md). For production, use the 1.x package: `pip install "chtypes<2"`.
+
 **If this row were inserted into this table on this ClickHouse version, what would happen?** chtypes answers with ClickHouse's own code: the real C++ type machinery, vendored per release into a native library behind the frozen `chs_*` C ABI and reached here through stdlib `ctypes`. Nothing semantic is reimplemented, so _"what does ClickHouse do with `256` into a `UInt8`?"_ is answered by ClickHouse rather than by a model of it. One peer binding among `{go, python, ts, rust}` — no language is privileged, and all four give one answer.
 
 Pure ctypes: no compiler, no build step. The only dependency is a zstd decompressor for the artifact layer, which is the standard library's own from Python 3.14 and the `backports.zstd` package before that.
@@ -9,9 +11,11 @@ Pure ctypes: no compiler, no build step. The only dependency is a zstd decompres
 Two things: this package, and at least one **artifact** — the per-version native library it `dlopen`s at runtime. The registry fetches the artifact on first use when autofetch is on (`Registry(autofetch=True)` or `CHTYPES_AUTOFETCH=1`), after verifying its signature and every byte against the signed statement; with autofetch off it answers only from what is already installed.
 
 ```sh
-uv add chtypes            # or: pip install chtypes
+uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 ```
 
+`uv add chtypes` and `pip install chtypes` never select a pre-release on their own: the specifier names a dev version, which is what allows one.
+
 ## Quickstart
 
 ```python

{chtypes-1.0.4 → chtypes-2.0.0.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chtypes"
-version = "1.0.4"
+version = "2.0.0.dev0"
 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-1.0.4 → chtypes-2.0.0.dev0}/src/chtypes/__init__.py

@@ -1,5 +1,11 @@
 """chtypes: ClickHouse's own type system, per version, from Python.
 
+2.0.0-dev: UNSTABLE, staging only, not for production. This pre-release speaks
+the ABI v2 dev description (spec/abi-v2/docs.md): it fetches only from the
+staging dev channel and trusts only its key, refuses locks and frozen fetches,
+caches under its own `v2-dev` root, and refuses a library built from any other
+dev fingerprint (rules r5 and r6).
+
 One question, exactly: *if this row were inserted into this ClickHouse table on
 this ClickHouse version, what would happen?* The answer comes from ClickHouse's
 real C++ machinery, vendored per release into a shared library behind the frozen
@@ -40,9 +46,10 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError as _PackageNotFound
 from importlib.metadata import version as _package_version
 
-from ._abi1._vocab import (
+from ._abi2._vocab import (
     EXPORT_NONE,
     DefaultKind,
+    DiscoverQueryParam,
     DocFlags,
     FilterOutcome,
     Format,
@@ -61,6 +68,7 @@ from .errors import (
     CODE_ARTIFACT_PINNED,
     CODE_ARTIFACT_UNPUBLISHED,
     CODE_ARTIFACT_UNTRUSTED,
+    CODE_CACHE_UNUSABLE,
     CODE_SOURCE_FORBIDDEN,
     CODE_SOURCE_INCOMPATIBLE,
     CODE_SOURCE_UNAUTHORIZED,
@@ -72,6 +80,7 @@ from .errors import (
     ArtifactPinnedError,
     ArtifactUnpublishedError,
     ArtifactUntrustedError,
+    CacheUnusableError,
     CallError,
     ChtypesError,
     InternalError,
@@ -114,6 +123,7 @@ __all__ = [
     "CODE_ARTIFACT_PINNED",
     "CODE_ARTIFACT_UNPUBLISHED",
     "CODE_ARTIFACT_UNTRUSTED",
+    "CODE_CACHE_UNUSABLE",
     "CODE_SOURCE_FORBIDDEN",
     "CODE_SOURCE_INCOMPATIBLE",
     "CODE_SOURCE_UNAUTHORIZED",
@@ -130,12 +140,14 @@ __all__ = [
     "Block",
     "BuildInfo",
     "BytesIn",
+    "CacheUnusableError",
     "CallError",
     "Capabilities",
     "ChtypesError",
     "Column",
     "Computed",
     "DefaultKind",
+    "DiscoverQueryParam",
     "DiscoveredColumn",
     "Discovery",
     "EngineCell",

{chtypes-1.0.4 → chtypes-2.0.0.dev0}/src/chtypes/__main__.py

@@ -2,16 +2,25 @@
 (docs/guides/fetch-v1.md).
 
     chtypes fetch <spelling>... | --all  [--platform <os-arch>] [--cache <dir>] [--lock <file>]
-                                         [--frozen] [--offline] [--update]
-    chtypes verify [--cache <dir>]       re-verify every installed build
-    chtypes list   [--cache <dir>] [--offline]
-    chtypes where  [--cache <dir>]       the cache root
+                                         [--frozen] [--offline] [--update] [--strict]
+    chtypes verify [--cache <dir>] [--strict]   re-verify every installed build
+    chtypes list   [--cache <dir>] [--offline] [--strict]
+    chtypes where  [--cache <dir>] [--strict]   the cache root
 
 A spelling is `26.8`, `26.8.15` or `26.8.15.10`. Exit statuses come from the
 `errors` table of spec/fetch-v1/constants.json (generated into the fetch layer
 as `ERROR_EXIT_CODES`); a usage error exits 2 and success exits 0. Progress and
 diagnostics go to stderr; `fetch` prints one installed library path per line on
 stdout.
+
+2.0.0-dev: UNSTABLE, staging only, not for production. This CLI speaks the ABI
+v2 dev channel (spec/abi-v2/docs.md, rules r5 and r6): it fetches only from
+https://registry-staging.wavehouse.dev/chtypes/v2-dev and trusts only the
+staging key; CHTYPES_ARTIFACTS_URL, CHTYPES_TRUSTED_KEYS and
+CHTYPES_ALLOW_UNSIGNED are ignored, each with one warning; --lock, --frozen and
+--update are refused before any network call; its default cache is
+${XDG_CACHE_HOME:-~/.cache}/chtypes/v2-dev, and an explicit one (--cache,
+CHTYPES_CACHE) is used through its v2-dev subroot.
 """
 
 from __future__ import annotations
@@ -24,11 +33,13 @@ from collections.abc import Sequence
 
 from . import __version__ as chtypes_version
 from . import _ocifetch as fetch_layer
+from ._ocifetch import _channel
 from ._ocifetch import _constants as C
-from ._ocifetch._ensure import _translate_transport_error, detect_host_platform
-from ._ocifetch._errors import ArtifactCorruptError, FetchError
+from ._ocifetch._ensure import _translate_transport_error, detect_host_platform, missing_notes
+from ._ocifetch._errors import ArtifactCorruptError, ArtifactMissingError, FetchError
+from ._ocifetch._faults import probe_roots
 from ._ocifetch._http import FetchPolicy, RetryPolicy, TransportError, fetch_from_bases
-from ._ocifetch._layout import resolve_cache_root
+from ._ocifetch._layout import resolve_cache_root, search_roots
 from ._ocifetch._lock import load_lock
 from .errors import ChtypesError
 from .registry import FetchOptions
@@ -66,6 +77,12 @@ def build_parser() -> argparse.ArgumentParser:
     parser = _Parser(
         prog="chtypes",
         description="Fetch, verify and locate chtypes artifacts (docs/guides/fetch-v1.md).",
+        epilog=(
+            "2.0.0-dev: UNSTABLE, staging only, not for production. Fetches only from the staging "
+            "dev channel and trusts only its key; --lock, --frozen and --update are refused; "
+            "CHTYPES_ARTIFACTS_URL, CHTYPES_TRUSTED_KEYS and CHTYPES_ALLOW_UNSIGNED are ignored "
+            "(spec/abi-v2/docs.md, rule r6)."
+        ),
     )
     parser.add_argument("--version", action="version", version=f"chtypes {_display_version()}")
     sub = parser.add_subparsers(dest="command", metavar="<command>")
@@ -75,6 +92,12 @@ def build_parser() -> argparse.ArgumentParser:
         p.add_argument(
             "--cache", metavar="<dir>", help="the cache directory (default: CHTYPES_CACHE)"
         )
+        p.add_argument(
+            "--strict",
+            action="store_true",
+            help="a cache that cannot be read is CHTYPES_CACHE_UNUSABLE, never not-installed "
+            "(default: CHTYPES_CACHE_STRICT=1)",
+        )
 
     fetch = sub.add_parser(
         "fetch",
@@ -151,6 +174,7 @@ def _options(args: argparse.Namespace, *, platform: str | None = None):
         lock_write = True
     fetch = FetchOptions(
         cache_dir=getattr(args, "cache", None),
+        strict_cache=True if getattr(args, "strict", False) else None,
         offline=getattr(args, "offline", False),
         frozen=getattr(args, "frozen", False),
         lock_path=lock_path,
@@ -188,6 +212,10 @@ def _published_tags(options) -> list[str]:
 
 
 def _cmd_fetch(args: argparse.Namespace) -> int:
+    # A dev SDK pins nothing: the refusal comes before anything else, the
+    # network above all (rule r6).
+    if (args.lock or args.frozen or args.update) and not _channel.active().pinnable:
+        raise ValueError(f"chtypes: {_channel.PINNING_REFUSED}")
     if args.all and args.spellings:
         raise ValueError("chtypes: give spellings or --all, not both")
     if not args.all and not args.spellings and not args.update:
@@ -225,8 +253,29 @@ def _cmd_fetch(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def _say_notes(options) -> None:
+    """What the cache says about itself in the default mode: a warning per root
+    or entry it could not read, and the 0.x hint."""
+    for note in missing_notes(options):
+        _say(f"chtypes: {note}")
+
+
 def _cmd_verify(args: argparse.Namespace) -> int:
-    results = fetch_layer.verify_installed(FetchOptions(cache_dir=args.cache)._to_options())
+    options = _options(args)
+    results = fetch_layer.verify_installed(options)
+    if not results:
+        # An empty pass must never look like a good one (public issue #486):
+        # say that nothing was verified, and why when the cache says why. In
+        # strict mode it is a failure, so a mounted cache can be health-checked.
+        root = resolve_cache_root(args.cache)
+        _say(f"chtypes: verified 0 builds under {root}")
+        _say_notes(options)
+        if options.resolved_strict():
+            raise ArtifactMissingError(
+                f"chtypes: no build is installed under {root}, and strict mode needs one"
+            )
+        return EXIT_OK
+    _say_notes(options)
     failed = 0
     for r in results:
         if not r.ok:
@@ -239,10 +288,12 @@ def _cmd_verify(args: argparse.Namespace) -> int:
 
 
 def _cmd_list(args: argparse.Namespace) -> int:
-    options = FetchOptions(cache_dir=args.cache, offline=args.offline)._to_options()
+    options = _options(args)
     installed = fetch_layer.list_installed(options)
     for r in sorted(installed, key=lambda r: (r.version, r.platform)):
         sys.stdout.write(f"installed {r.version} {r.platform} {r.dir}\n")
+    sys.stdout.flush()
+    _say_notes(options)
     if not args.offline:
         for tag in _published_tags(options):
             sys.stdout.write(f"published {tag} support unknown\n")
@@ -251,6 +302,10 @@ def _cmd_list(args: argparse.Namespace) -> int:
 
 
 def _cmd_where(args: argparse.Namespace) -> int:
+    options = _options(args)
+    if options.resolved_strict():
+        # Strict mode checks the root before naming it.
+        probe_roots(search_roots(options.cache_dir, options.system_dirs), strict=True)
     sys.stdout.write(f"{resolve_cache_root(args.cache)}\n")
     return EXIT_OK
 

{chtypes-1.0.4/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/__init__.py

@@ -1,4 +1,4 @@
-"""The ABI v1 loader and generated declaration layer (plan
+"""The ABI v2 loader and generated declaration layer (plan
 PLAN-sdk-v1-ffi-2026-10-01.md), private to this binding. Not part of `chtypes`'s
 public surface: the public API (`chtypes.library`, `chtypes.registry`) is built
 over it, and re-exports the vocabularies and errors it defines.
@@ -7,11 +7,13 @@ over it, and re-exports the vocabularies and errors it defines.
   handle classes, the typed call wrappers on `Api`, and the test-only
   `invoke_by_name()` dispatcher.
 - `_vocab`: GENERATED -- `Format`, `Status`, `Outcome`, `Verdict`, `Reason`,
-  `Source`, `DefaultKind`, `DocFlags` and the facts the description attaches.
+  `Source`, `DefaultKind`, `DiscoverQueryParam`, `DocFlags` and the facts the
+  description attaches, each vocabulary with its unknown(n) member (rule r3).
 - `_errors`: the public `chtypes.errors` classes, re-exported under the names
   `_errmap` uses.
 - `_errmap`: GENERATED -- the sdk.json status/reason -> `_errors` class maps.
-- `_loader`: hand-written -- `open()`/`open_unverified()`, the loader steps.
+- `_loader`: hand-written -- `open()`/`open_unverified()`, the loader steps,
+  and rule r6's exact refusal of another fingerprint.
 """
 
 from __future__ import annotations

{chtypes-1.0.4/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_decls.py

@@ -1,9 +1,9 @@
-# GENERATED by scripts/abi-v1/gen.py from spec/abi-v1/abi.json (CHS_ABI_FINGERPRINT sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285) — DO NOT EDIT  # noqa: E501
-"""The Python binding's generated ABI v1 layer: ctypes signatures, the handle
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — DO NOT EDIT  # noqa: E501
+"""The Python binding's generated ABI v2 layer: ctypes signatures, the handle
 classes, the two-phase resolve functions and invoke_by_name(), the test-only
-dispatcher the conformance suite drives from tests/fixtures/abi-v1/cases.json.
+dispatcher the conformance suite drives from tests/fixtures/abi-v2/cases.json.
 See scripts/abi-v1/emit/python.py's module docstring for the design this file
-implements and why. This is the ONLY python/src/chtypes/_abi1 file that reads
+implements and why. This is the ONLY python/src/chtypes/_abi2 file that reads
 a chs_* attribute (scripts/abi-v1/check-no-hand-decls.py exempts it by its
 banner, above); every other file in this package calls the non-chs_-prefixed
 names this module exposes instead.
@@ -18,8 +18,14 @@ from dataclasses import dataclass, field
 
 from . import _errmap
 
-CHS_ABI_VERSION = 1
-CHS_ABI_FINGERPRINT = "sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285"
+CHS_ABI_VERSION = 2
+CHS_ABI_FINGERPRINT = "sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3"
+
+# The description's stability: "unstable" while this generation is being
+# designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after
+# (spec/abi-v2/docs.md, rule r6). A dev SDK refuses any other fingerprint with
+# the dev message (_loader.py).
+CHS_ABI_STABILITY = "unstable"
 
 # sdk.json's loader.cross_check: (build_info field, predicate field, how to
 # compare), read by _loader.py's step 5 without it ever touching sdk.json
@@ -516,7 +522,7 @@ class Api:
         cls = _errmap.call_error_class(name)
         message = info.message if info else b""
         if name not in STATUS_BY_NAME:
-            message = f"status {status} is outside the closed chs_status set".encode() + (
+            message = f"call status unknown({status}) is outside the closed set".encode() + (
                 b": " + message if message else b""
             )
         raise cls(
@@ -927,7 +933,7 @@ def resolve_all(lib: ctypes.CDLL) -> Api:
     time step 6 runs, step 3 has already proven it exists). The first symbol
     ctypes cannot dlsym raises MissingSymbol(name); _loader.py's step 6 turns
     that into "missing_symbol:<name>", matching every missing-<sym> stub
-    variant (tests/fixtures/abi-v1/cases.json), chs_build_info and
+    variant (tests/fixtures/abi-v2/cases.json), chs_build_info and
     chs_clickhouse_version included -- loader step 4 needs chs_build_info
     already resolved, which is exactly why this sweep must run before it."""
     raw: dict = {}
@@ -1028,7 +1034,7 @@ def invoke_by_name(api: Api, name: str, args: Iterable[object] = ()) -> InvokeRe
     (or None, where nullable) for handle. Output parameters are never
     supplied by the caller: this dispatcher allocates them, and decodes them
     into the returned InvokeResult. Test-only: every chs_ spelling below is
-    why this file, alone in python/src/chtypes/_abi1, carries the generated
+    why this file, alone in python/src/chtypes/_abi2, carries the generated
     banner check-no-hand-decls.py exempts."""
     spec = FUNCTIONS[name]
     fn = api._raw[name]

{chtypes-1.0.4/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_errmap.py

@@ -1,7 +1,7 @@
-# GENERATED by scripts/abi-v1/gen.py from spec/abi-v1/abi.json (CHS_ABI_FINGERPRINT sha256:856e5cb7543db291b4db716662bf6e487b2258973b959bbf5d58b4bd46d73285) — DO NOT EDIT  # noqa: E501
-"""spec/abi-v1/sdk.json's error-mapping tables, as references to the
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:8ec0c6941f000aa07bfb9fbfef20205d3ee0a588833856bd12270ba42912bfb3) — DO NOT EDIT  # noqa: E501
+"""spec/abi-v2/sdk.json's error-mapping tables, as references to the
 public classes (python/src/chtypes/errors.py, re-exported by
-python/src/chtypes/_abi1/_errors.py). Only the MAPPING is generated: the
+python/src/chtypes/_abi2/_errors.py). Only the MAPPING is generated: the
 classes themselves are stable across a regeneration (plan section 3.4), so a
 status renumbering or a new loader refusal reason changes this file, never
 the classes.

{chtypes-1.0.4/src/chtypes/_abi1 → chtypes-2.0.0.dev0/src/chtypes/_abi2}/_loader.py

@@ -1,4 +1,4 @@
-"""The ABI v1 loader, Python half (plan PLAN-sdk-v1-ffi section 3.2/3.3).
+"""The ABI v2 loader, Python half (plan PLAN-sdk-v1-ffi section 3.2/3.3).
 
 Decoupled from the fetch PRs on purpose (plan section 3.1): `open()` takes a
 small, loader-owned `predicate` mapping rather than the fetch module's
@@ -8,13 +8,13 @@ wired up; `predicate` is passed through exactly as that seam promises.
 
 Every `chs_*` spelling in this module is forbidden by
 scripts/abi-v1/check-no-hand-decls.py (it is not a generated file), so this
-calls ONLY python/src/chtypes/_abi1/_decls.py's non-`chs_`-prefixed surface:
+calls ONLY python/src/chtypes/_abi2/_decls.py's non-`chs_`-prefixed surface:
 `resolve_abi_version()`, `resolve_all()`, and the `Api` object they return.
 
 Steps 1-6 run in the order plan section 3.2 gives (with step 6's full
 resolve-all sweep run right after step 3, BEFORE step 4's
 `chs_build_info()` call -- step 4 needs that symbol already resolved, and
-`tests/fixtures/abi-v1/cases.json`'s `missing-chs_build_info` and
+`tests/fixtures/abi-v2/cases.json`'s `missing-chs_build_info` and
 `missing-chs_clickhouse_version` stub variants both expect the step 6
 `missing_symbol:<name>` reason, not a step 4 one, which is only possible if
 the full symbol sweep happens before chs_build_info is ever called). Step 7
@@ -54,6 +54,25 @@ def _refuse(reason: str, path: str, want: object = None, got: object = None) ->
     raise cls(reason=reason, path=path, want=want, got=got)
 
 
+def dev_fingerprint_message(sdk: str, library: str) -> str:
+    """Rule r6's exact refusal of a library whose fingerprint is not this dev
+    SDK's (spec/abi-v2/docs.md): `sdk` is the SDK's own fingerprint and
+    `library` the library's, both full "sha256:" spellings."""
+    return f"this SDK speaks dev fingerprint {sdk}; the library has {library} — update your dev SDK"
+
+
+def _refuse_fingerprint(path: str, got: object) -> None:
+    """Loader step 4's fingerprint refusal: CHTYPES_ARTIFACT_INCOMPATIBLE.
+    While this generation's description is unstable (a 2.0.0-dev SDK), its
+    message is exactly rule r6's; after the lock it is the ordinary refusal."""
+    want = _decls.CHS_ABI_FINGERPRINT
+    cls = _errmap.loader_error_class("fingerprint")
+    if _decls.CHS_ABI_STABILITY == "unstable":
+        message = dev_fingerprint_message(want, str(got))
+        raise cls(message, reason="fingerprint", path=path, want=want, got=got)
+    raise cls(reason="fingerprint", path=path, want=want, got=got)
+
+
 def _glibc_version() -> tuple[int, int] | None:
     """Resolve `gnu_get_libc_version` dynamically from the running process:
     `ctypes.CDLL(None)` is the process image's own global symbols (glibc's,
@@ -193,9 +212,7 @@ def _open(
     info = _parse_build_info(raw, path)
 
     if info["abi_fingerprint"] != _decls.CHS_ABI_FINGERPRINT:
-        _refuse(
-            "fingerprint", path, want=_decls.CHS_ABI_FINGERPRINT, got=info.get("abi_fingerprint")
-        )
+        _refuse_fingerprint(path, info.get("abi_fingerprint"))
 
     if not skip_step5:
         _cross_check(info, predicate, path)
@@ -231,7 +248,7 @@ def open(
     timezone: bytes = b"",
     defaults: bytes = b"",
 ) -> LoadResult:
-    """Load and verify a v1 artifact at `path` against its (already verified
+    """Load and verify an ABI v2 artifact at `path` against its (already verified
     elsewhere) signed `predicate`, then set the image zone (`timezone`, empty
     = UTC) and the default settings (`defaults`, a JSON object of string
     values, empty for none): step 7. Raises an artifact error naming the exact