chtypes 2.0.0.dev1__tar.gz → 2.0.0.dev3__tar.gz

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/CHANGELOG.md

@@ -6,6 +6,10 @@ The four bindings in this repository are released together and give one answer,
 
 ## [Unreleased]
 
+### Added
+
+- A 2.0.0-dev SDK prefers the newest build of its own fingerprint (#511). A version request resolves `<tag>--fp-<fingerprint>` first, the alias the staging dev registry serves beside every dev tag, with the binding's own generated ABI fingerprint, and the tag itself only when every base answers the alias 404; any other failure of the alias request is that failure, with no fallback, and an alias whose index lacks the platform is `CHTYPES_ARTIFACT_UNPUBLISHED`. The dev channel's cache lookups (the installed-build lookup a registry open makes first, the offline answer, and the monotonic rule of a fetch) now see only records whose signed `abi_fingerprint` is the SDK's own, so a newer build of another fingerprint, installed by another dev SDK in the shared cache, is never returned or kept over this one's own, and is never removed or rewritten. So a dev build of a newer fingerprint no longer strands an older dev SDK until its consumers upgrade. Trust is unchanged (the signed predicate and the load checks decide), a listing never shows an alias, nothing records one, `list` and `where` are unchanged, and there is no option: both steps are the dev channel's alone, and the v1 contract and every production channel never take them. The rule is `docs/guides/fetch-v1.md` section 3, and the `dev-alias-*`, `resolve-installed-dev-alias-*` and `list-tags-dev-alias` conformance cases hold all four bindings to it.
+
 ## [1.1.0] — 2026-10-06
 
 ### Added

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chtypes
-Version: 2.0.0.dev1
+Version: 2.0.0.dev3
 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,7 +19,9 @@ 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"`.
+> **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. A dev SDK prefers the newest build of its own fingerprint: it resolves `<tag>--fp-<its fingerprint>` first and the tag only when no such build exists, and its cache lookups ignore another dev SDK's builds in a shared cache, so a newer dev fingerprint never strands it (§3 of [`docs/guides/fetch-v1.md`](../docs/guides/fetch-v1.md)). 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"`.
+>
+> An explicit cache directory gets the `v2-dev` subroot whether it comes from `CHTYPES_CACHE` or from `FetchOptions(cache_dir=...)`: the layout is under `<cache_dir>/v2-dev`, never in the directory itself, so code that inspects or pre-populates a cache looks there; `chtypes.cache_root` and `chtypes.search_dirs` return the resolved paths. `CHTYPES_OFFLINE=1` is the environment twin of `FetchOptions(offline=True)` and `--offline`: the cache only, no request.
 
 **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.
 
@@ -41,18 +43,18 @@ uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 import chtypes
 from chtypes import Format, Registry
 
-chtypes.setup(timezone="UTC")             # once, before the first open (optional)
+chtypes.setup(timezone="UTC")  # once, before the first open (optional)
 registry = Registry(autofetch=True)
-library = registry.for_version("26.8")    # a release line or an exact version
+library = registry.for_version("26.8")  # a release line or an exact version
 
 ddl = b"CREATE TABLE t (x UInt8, ts DateTime DEFAULT now()) ENGINE = Memory"
 with library.compile_table(ddl) as schema:
     batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n')
 
 row = batch.rows[0]
-print(batch.outcome)                  # accepted
-print(row.values[0].text)             # b'0'          what would actually be stored
-print(row.transformed[0].reason)      # overflow_wrap which is the product
+print(batch.outcome)  # accepted
+print(row.values[0].text)  # b'0'          what would actually be stored
+print(row.transformed[0].reason)  # overflow_wrap which is the product
 ```
 
 The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is why chtypes exists. Names, SQL, messages and renderings come back as `bytes`, never decoded for you: a column name that is not valid UTF-8 round-trips exactly.

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/README.md

@@ -1,6 +1,8 @@
 # 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"`.
+> **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. A dev SDK prefers the newest build of its own fingerprint: it resolves `<tag>--fp-<its fingerprint>` first and the tag only when no such build exists, and its cache lookups ignore another dev SDK's builds in a shared cache, so a newer dev fingerprint never strands it (§3 of [`docs/guides/fetch-v1.md`](../docs/guides/fetch-v1.md)). 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"`.
+>
+> An explicit cache directory gets the `v2-dev` subroot whether it comes from `CHTYPES_CACHE` or from `FetchOptions(cache_dir=...)`: the layout is under `<cache_dir>/v2-dev`, never in the directory itself, so code that inspects or pre-populates a cache looks there; `chtypes.cache_root` and `chtypes.search_dirs` return the resolved paths. `CHTYPES_OFFLINE=1` is the environment twin of `FetchOptions(offline=True)` and `--offline`: the cache only, no request.
 
 **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.
 
@@ -22,18 +24,18 @@ uv add "chtypes>=2.0.0.dev0"            # or: pip install "chtypes>=2.0.0.dev0"
 import chtypes
 from chtypes import Format, Registry
 
-chtypes.setup(timezone="UTC")             # once, before the first open (optional)
+chtypes.setup(timezone="UTC")  # once, before the first open (optional)
 registry = Registry(autofetch=True)
-library = registry.for_version("26.8")    # a release line or an exact version
+library = registry.for_version("26.8")  # a release line or an exact version
 
 ddl = b"CREATE TABLE t (x UInt8, ts DateTime DEFAULT now()) ENGINE = Memory"
 with library.compile_table(ddl) as schema:
     batch = schema.rows(Format.JSON_EACH_ROW, b'{"x":256}\n')
 
 row = batch.rows[0]
-print(batch.outcome)                  # accepted
-print(row.values[0].text)             # b'0'          what would actually be stored
-print(row.transformed[0].reason)      # overflow_wrap which is the product
+print(batch.outcome)  # accepted
+print(row.values[0].text)  # b'0'          what would actually be stored
+print(row.transformed[0].reason)  # overflow_wrap which is the product
 ```
 
 The row is **accepted** and `256` is silently stored as `0`. That report — `transformed` — is why chtypes exists. Names, SQL, messages and renderings come back as `bytes`, never decoded for you: a column name that is not valid UTF-8 round-trips exactly.

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/pyproject.toml

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

@@ -53,13 +53,14 @@ from ._abi2._vocab import (
     DocFlags,
     FilterOutcome,
     Format,
+    MergeReason,
     Outcome,
     Reason,
     Source,
     Status,
     Verdict,
 )
-from ._input import BytesIn, Settings
+from ._input import BytesIn, ServerProfile, Settings
 from ._setup import setup
 from .errors import (
     CODE_ARTIFACT_CORRUPT,
@@ -92,9 +93,10 @@ from .errors import (
     UnsupportedError,
     UsageError,
 )
-from .library import Block, Filter, Library, Schema, open_unverified
-from .registry import FetchOptions, Registry, Resolved, TrustedKey
+from .library import Block, Filter, Library, Schema, Server, open_unverified
+from .registry import FetchOptions, Registry, Resolved, TrustedKey, cache_root, search_dirs
 from .results import (
+    AtMergeEntry,
     BatchResult,
     BuildInfo,
     Capabilities,
@@ -111,6 +113,8 @@ from .results import (
     Header,
     RowResult,
     SchemaDescription,
+    SchemaReplicated,
+    SchemaServer,
     Span,
     Transform,
     Value,
@@ -136,6 +140,7 @@ __all__ = [
     "ArtifactPinnedError",
     "ArtifactUnpublishedError",
     "ArtifactUntrustedError",
+    "AtMergeEntry",
     "BatchResult",
     "Block",
     "BuildInfo",
@@ -164,6 +169,7 @@ __all__ = [
     "Header",
     "InternalError",
     "Library",
+    "MergeReason",
     "Outcome",
     "Reason",
     "Registry",
@@ -172,6 +178,10 @@ __all__ = [
     "Schema",
     "SchemaDescription",
     "SchemaError",
+    "SchemaReplicated",
+    "SchemaServer",
+    "Server",
+    "ServerProfile",
     "Settings",
     "Source",
     "SourceForbiddenError",
@@ -186,7 +196,9 @@ __all__ = [
     "UsageError",
     "Value",
     "Verdict",
+    "cache_root",
     "open_unverified",
+    "search_dirs",
     "setup",
 ]
 

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/__main__.py

@@ -5,7 +5,7 @@
                                          [--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
+    chtypes where  [--cache <dir>] [--strict] [--all]   the cache root; --all: every search dir
 
 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
@@ -137,7 +137,10 @@ def build_parser() -> argparse.ArgumentParser:
     fetch.add_argument(
         "--offline",
         action="store_true",
-        help="never touch a source: installed and verified, or CHTYPES_ARTIFACT_MISSING",
+        help=(
+            "never touch a source: installed and verified, or CHTYPES_ARTIFACT_MISSING "
+            "(or set CHTYPES_OFFLINE=1)"
+        ),
     )
 
     verify = sub.add_parser(
@@ -154,11 +157,22 @@ def build_parser() -> argparse.ArgumentParser:
     )
     cache_option(listing)
     listing.add_argument(
-        "--offline", action="store_true", help="list only what is installed; no network"
+        "--offline",
+        action="store_true",
+        help="list only what is installed; no network (or set CHTYPES_OFFLINE=1)",
     )
 
-    where = sub.add_parser("where", help="the cache root", description="Print the cache root.")
+    where = sub.add_parser(
+        "where",
+        help="the cache root",
+        description="Print the cache root; with --all, every directory searched.",
+    )
     cache_option(where)
+    where.add_argument(
+        "--all",
+        action="store_true",
+        help="every directory searched, in order, the cache root first (one per line)",
+    )
     return parser
 
 
@@ -294,7 +308,7 @@ def _cmd_list(args: argparse.Namespace) -> int:
         sys.stdout.write(f"installed {r.version} {r.platform} {r.dir}\n")
     sys.stdout.flush()
     _say_notes(options)
-    if not args.offline:
+    if not options.resolved_offline():
         for tag in _published_tags(options):
             sys.stdout.write(f"published {tag} support unknown\n")
     sys.stdout.flush()
@@ -306,6 +320,10 @@ def _cmd_where(args: argparse.Namespace) -> int:
     if options.resolved_strict():
         # Strict mode checks the root before naming it.
         probe_roots(search_roots(options.cache_dir, options.system_dirs), strict=True)
+    if args.all:
+        for directory in search_roots(options.cache_dir, options.system_dirs):
+            sys.stdout.write(f"{directory}\n")
+        return EXIT_OK
     sys.stdout.write(f"{resolve_cache_root(args.cache)}\n")
     return EXIT_OK
 

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_abi2/_decls.py

@@ -1,4 +1,4 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — 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-v2/cases.json.
@@ -19,7 +19,7 @@ from dataclasses import dataclass, field
 from . import _errmap
 
 CHS_ABI_VERSION = 2
-CHS_ABI_FINGERPRINT = "sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232"
+CHS_ABI_FINGERPRINT = "sha256:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a"
 
 # The description's stability: "unstable" while this generation is being
 # designed, so CHS_ABI_FINGERPRINT moves with every change, and "locked" after

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_abi2/_errmap.py

@@ -1,4 +1,4 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — 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/_abi2/_errors.py). Only the MAPPING is generated: the

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_abi2/_vocab.py

@@ -1,10 +1,10 @@
-# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:d87e91be2bbe75b985c38224268c2f7dc5d8236dab0a4b4d61357c6dfdc1a232) — DO NOT EDIT  # noqa: E501
+# GENERATED by scripts/abi-v1/gen.py --major 2 from spec/abi-v2/abi.json (CHS_ABI_FINGERPRINT sha256:4129dccc3f4e698dedb0e99cae413f5240085f633c5a1244e2c55bf7a7bb6c3a) — DO NOT EDIT  # noqa: E501
 """The Python binding's generated vocabularies, from spec/abi-v2/abi.json: the C
 enums (`Format`, `Status`), the document vocabularies (`Outcome`, `FilterOutcome`,
-`Verdict`, `DefaultKind`, `Reason`, `Source`, `DiscoverQueryParam`) with the facts the
-description attaches to each value (`Format.ch_name`, `Reason` lossy, `Source`
-is_stored, `Verdict.answered`), and the `DocFlags` groups. No other file in this
-package keeps a copy of any of it.
+`Verdict`, `DefaultKind`, `MergeReason`, `Reason`, `Source`, `DiscoverQueryParam`) with the
+facts the description attaches to each value (`Format.ch_name`, `Reason` lossy,
+`Source` is_stored, `Verdict.answered`), and the `DocFlags` groups. No other file in
+this package keeps a copy of any of it.
 
 Rule r3 (spec/abi-v2/docs.md): every vocabulary has an unknown(n) member, and a
 value the description does not list reads as it, carrying the raw value, for that
@@ -225,6 +225,30 @@ class DefaultKind(StrEnum):
         return cls(text)
 
 
+class MergeReason(StrEnum):
+    """What a merge would do to one row of the part an INSERT writes, as a batch's
+    `at_merge` reports it."""
+
+    TTL_DELETE = "ttl_delete"
+    TTL_COLUMN_RESET = "ttl_column_reset"
+
+    @classmethod
+    def _missing_(cls, value: object) -> MergeReason | None:
+        return _unknown_str(cls, value)
+
+    @property
+    def known(self) -> bool:
+        """Whether the description lists this value: False for exactly the unknown(n)
+        member an unlisted value reads as (rule r3)."""
+        return type(self)._value2member_map_.get(self._value_) is self
+
+    @classmethod
+    def of(cls, text: str) -> MergeReason:
+        """Map a document's spelling. One the description does not list is kept as
+        this vocabulary's unknown(n) member, carrying it (rule r3)."""
+        return cls(text)
+
+
 class DiscoverQueryParam(StrEnum):
     """A query parameter of the SQL `discover_query` returns, which the caller binds
     when it runs the query."""
@@ -383,6 +407,7 @@ DESCRIBED_VOCABULARIES: Final[dict[str, type]] = {
     "chs_status": Status,
     "chs_format": Format,
     "transform_reason": Reason,
+    "merge_reason": MergeReason,
     "value_src": Source,
     "row_outcome": Outcome,
     "batch_outcome": Outcome,

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_decode.py

@@ -28,9 +28,10 @@ import json
 from collections.abc import Callable, Mapping
 from typing import Any
 
-from ._abi2._vocab import DefaultKind, FilterOutcome, Outcome, Reason, Source, Verdict
+from ._abi2._vocab import DefaultKind, FilterOutcome, MergeReason, Outcome, Reason, Source, Verdict
 from .errors import ArtifactCorruptError, internal
 from .results import (
+    AtMergeEntry,
     BatchResult,
     BuildInfo,
     Capabilities,
@@ -47,6 +48,8 @@ from .results import (
     Header,
     RowResult,
     SchemaDescription,
+    SchemaReplicated,
+    SchemaServer,
     Span,
     Transform,
     Value,
@@ -323,6 +326,29 @@ def _engine_cell(obj: dict[str, Any], where: str) -> EngineCell:
     )
 
 
+def _int_list(obj: Mapping[str, Any], key: str, where: str) -> tuple[int, ...] | None:
+    """A list of non-negative integers: None when absent."""
+    if obj.get(key) is None:
+        return None
+    out = []
+    for item in _list(obj, key, where):
+        if isinstance(item, bool) or not isinstance(item, int) or item < 0:
+            raise _wrong(where, key, "an array of non-negative integers", item)
+        out.append(item)
+    return tuple(out)
+
+
+def _at_merge(obj: dict[str, Any], where: str) -> AtMergeEntry:
+    # An unlisted reason is its unknown(n): kept, never a failure (rule r3).
+    return AtMergeEntry(
+        row=_int(obj, "row", where),
+        reason=MergeReason.of(_text(obj, "reason", where)),
+        column=_bytes_or_none(obj, "column", where),
+        stored=_bytes_or_none(obj, "stored", where),
+        input_rows=_int_list(obj, "input_rows", where),
+    )
+
+
 def _engine_rows(obj: Mapping[str, Any], where: str) -> tuple[tuple[EngineCell, ...], ...]:
     rows = []
     for i, row in enumerate(_list(obj, "engine_rows", where)):
@@ -409,6 +435,8 @@ def decode_batch(raw: bytes, export: bytes | None) -> BatchResult:
         framing=None
         if framing is None
         else _framing(_obj(framing, where, "framing"), f"{where}.framing"),
+        unsupported_settings=_name_list(obj, "unsupported_settings", where),
+        at_merge=_objects(obj, "at_merge", where, _at_merge),
     )
 
 
@@ -449,10 +477,55 @@ def _column(obj: dict[str, Any], where: str) -> Column:
     )
 
 
+def _string_map(obj: Mapping[str, Any], key: str, where: str) -> dict[str, str] | None:
+    """An object of plain JSON strings (a server's settings or macros, the
+    caller's own values given back): None when absent, a dict, even an empty
+    one, when present, so absent and `{}` stay apart."""
+    value = obj.get(key)
+    if value is None:
+        return None
+    inner = _obj(value, where, key)
+    out: dict[str, str] = {}
+    for name, item in inner.items():
+        if not isinstance(item, str):
+            raise _wrong(f"{where}.{key}", name, "a string", item)
+        out[name] = item
+    return out
+
+
+def _server(obj: dict[str, Any], where: str) -> SchemaServer:
+    return SchemaServer(
+        timezone=_text(obj, "timezone", where),
+        settings=_string_map(obj, "settings", where) or {},
+        macros=_string_map(obj, "macros", where),
+    )
+
+
+def _replicated(obj: dict[str, Any], where: str) -> SchemaReplicated:
+    return SchemaReplicated(
+        zookeeper_path=_bytes(obj, "zookeeper_path", where),
+        replica_name=_bytes(obj, "replica_name", where),
+    )
+
+
 def decode_schema_description(raw: bytes) -> SchemaDescription:
     where = "schema_description"
     obj = _obj(strict_loads(raw, where), where)
-    return SchemaDescription(columns=_objects(obj, "columns", where, _column))
+    # Both are absent on a schema compiled without a server, so that document
+    # decodes exactly as it did before servers existed.
+    server = obj.get("server")
+    replicated = obj.get("replicated")
+    return SchemaDescription(
+        columns=_objects(obj, "columns", where, _column),
+        server=None
+        if server is None
+        else _server(_obj(server, where, "server"), f"{where}.server"),
+        replicated=(
+            None
+            if replicated is None
+            else _replicated(_obj(replicated, where, "replicated"), f"{where}.replicated")
+        ),
+    )
 
 
 def _discovered(obj: dict[str, Any], where: str) -> DiscoveredColumn:

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_input.py

@@ -12,10 +12,11 @@ from __future__ import annotations
 import base64
 import json
 from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
 
 from .errors import misuse
 
-__all__ = ["BytesIn", "Settings"]
+__all__ = ["BytesIn", "ServerProfile", "Settings"]
 
 BytesIn = bytes | str
 Settings = Mapping[str, str]
@@ -107,3 +108,43 @@ def columns_json(columns: Sequence[BytesIn] | None) -> bytes | None:
         except UnicodeDecodeError:
             names.append({"name_b64": base64.b64encode(raw).decode("ascii")})
     return _dump(names)
+
+
+@dataclass(frozen=True, slots=True)
+class ServerProfile:
+    """One ClickHouse server, as the library's `input:server_profile` describes
+    it. Every field is optional and passed through as given: the library
+    validates the zone with DateLUT, each setting with the server's own SET
+    check, and the macros with ClickHouse's own reader. The binding validates
+    nothing in it.
+
+    `timezone` is the server's zone, the one its `timezone()` returns; None or
+    "" leaves it undescribed (omitted) and the image zone applies. `settings` is
+    what the server's profile applies to every query, layered under a schema's
+    and a call's own; None omits it, and `{}` is sent as `{}`. `macros` is the
+    server's `<macros>`: None omits it, and the server's macros are UNKNOWN (a
+    schema whose engine reads one is declined); a mapping, even an empty one, is
+    sent (`{}` when empty) and is the server's COMPLETE set."""
+
+    timezone: str | None = None
+    settings: Settings | None = None
+    macros: Settings | None = None
+
+
+def server_profile_json(profile: ServerProfile) -> bytes:
+    """The profile document: an empty or absent zone and an absent map are
+    omitted; a present map is sent as given, `{}` when empty. Absent `macros` is
+    not empty `macros`."""
+    if not isinstance(profile, ServerProfile):
+        raise TypeError(f"profile must be a ServerProfile, not {type(profile).__name__}")
+    doc: dict[str, object] = {}
+    if profile.timezone is not None:
+        if not isinstance(profile.timezone, str):
+            raise TypeError(f"timezone must be str, not {type(profile.timezone).__name__}")
+        if profile.timezone != "":
+            doc["timezone"] = profile.timezone
+    if profile.settings is not None:
+        doc["settings"] = _string_map(profile.settings, "settings")
+    if profile.macros is not None:
+        doc["macros"] = _string_map(profile.macros, "macros")
+    return _dump(doc)

{chtypes-2.0.0.dev1 → chtypes-2.0.0.dev3}/src/chtypes/_ocifetch/_channel.py

@@ -18,6 +18,19 @@ five ways:
   used through its subroot `<cache>/v2-dev`, never as a whole layout;
 - a signed predicate must say abi 2.
 
+It also resolves one tag the v1 contract never asks for: a version request
+fetches `<tag>--fp-<its own fingerprint>` first, the newest dev build of the ABI
+this binding speaks, and falls back to `<tag>` only when no base has that alias
+(docs/guides/fetch-v1.md §3, "The dev channel's alias step"), so a dev build of a
+newer fingerprint never strands this one. Its cache lookups (`resolve_installed`,
+and `ensure`'s offline answer and its monotonic rule) see only the records whose
+signed `abi_fingerprint` is its own: a build of another fingerprint in a shared
+cache is never returned and never kept over this one's own, and it is never
+removed or rewritten either. It is automatic, with no override; the trust checks
+are unchanged, and a listing never shows an alias. The fingerprint
+is the generated `CHS_ABI_FINGERPRINT` of the ABI layer (`chtypes._abi2._decls`),
+never a hand-written copy.
+
 The v1 contract itself stays in this package, unchanged, because the fetch-v1
 conformance cases (tests/fixtures/fetch-v1) are its specification and the dev
 channel shares every other rule with it. Only a test run reaches it:
@@ -29,16 +42,19 @@ override a user can reach.
 from __future__ import annotations
 
 import os
+import re
 import sys
 import threading
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
 from typing import Final, Protocol
 
+from chtypes._abi2._decls import CHS_ABI_FINGERPRINT
 from chtypes._ocifetch import _constants as C
 from chtypes._ocifetch._dsse import TrustedKey
 
 __all__ = [
+    "ALIAS_SEPARATOR",
     "DEV_ABI_GENERATION",
     "DEV_CACHE_DIR",
     "DEV_CHANNEL_BASE",
@@ -50,12 +66,15 @@ __all__ = [
     "PinningRefusedError",
     "abi",
     "active",
+    "alias_tag",
     "allow_overrides_for_tests",
     "channel_name",
     "enforce",
     "ignored_settings_warned",
     "pinning_requested",
     "trusted_keys",
+    "use_own_fingerprint_for_tests",
+    "visible",
     "use_dev_channel_for_tests",
     "use_fetch_v1_for_tests",
 ]
@@ -69,12 +88,20 @@ DEV_KEY_ID: Final = "824345f9bcf8e5bf"
 DEV_KEY_HEX: Final = "5cd30c53c65a1ebc2d85836a41deb06661bb0ae7b658adb9eb116ec2db8e9b1c"
 # The dev channel's cache directory name: the default root's last element and
 # an explicit cache's subroot (rule r5).
+# The environment twin of the offline option (public issue #528): CHTYPES_OFFLINE=1
+# reads the cache only and makes no request. It names no source, so rule r6 holds.
+# Not a generated constant: the generated set is the v1 fetch contract's.
+ENV_OFFLINE_NAME: Final = "CHTYPES_OFFLINE"
 DEV_CACHE_DIR: Final = "v2-dev"
 # The verified.json schema the dev channel writes, and the only one it reads (rule r5).
 DEV_RECORD_SCHEMA: Final = 2
 # The abi a dev predicate must carry.
 DEV_ABI_GENERATION: Final = 2
 
+# Joins a tag and a fingerprint into the dev channel's alias tag:
+# <tag>--fp-<64 lowercase hex> (docs/guides/fetch-v1.md §3).
+ALIAS_SEPARATOR: Final = "--fp-"
+
 # What every lock, frozen or update request gets from a 2.0.0-dev SDK, before
 # any network call (rule r6).
 PINNING_REFUSED: Final = (
@@ -98,6 +125,11 @@ class Channel:
     keys: tuple[dict[str, str], ...]  # {"keyid", "ed25519_hex"}: the default trust
     overridable: bool  # the base, trust and unsigned overrides are honored
     pinnable: bool  # lock, frozen and update are honored
+    # The fingerprint, 64 lowercase hex, this contract's SDK speaks: a version
+    # request resolves its alias tag before the tag itself, and the cache
+    # lookups see only records signed with it. "" does neither (the v1 contract
+    # and every production channel).
+    own_fingerprint: str = ""
 
 
 # What a 2.0.0-dev SDK speaks, and what every process speaks unless a test
@@ -113,6 +145,7 @@ DEV_CHANNEL: Final = Channel(
     keys=({"keyid": DEV_KEY_ID, "ed25519_hex": DEV_KEY_HEX},),
     overridable=False,
     pinnable=False,
+    own_fingerprint=CHS_ABI_FINGERPRINT.removeprefix("sha256:"),
 )
 
 # The v1 contract the fetch-v1 conformance cases specify, from the generated
@@ -198,6 +231,49 @@ def allow_overrides_for_tests() -> Callable[[], None]:
     return _use(replace(DEV_CHANNEL, overridable=True))
 
 
+_FINGERPRINT_HEX = re.compile(r"[0-9a-f]{64}")
+
+
+def use_own_fingerprint_for_tests(fingerprint: str) -> Callable[[], None]:
+    """Make this TEST run's active contract speak `fingerprint` (64 lowercase
+    hex) as the dev channel speaks its own: a version request resolves that
+    fingerprint's alias tag first, and the cache lookups see only records
+    signed with it. The fetch-v1 conformance cases that carry
+    `request.own_fingerprint` run under it, against fixtures that name a
+    fixture fingerprint. Everything else stays the active contract's. Returns
+    the restore function; raises outside a test run or on a fingerprint that is
+    not 64 lowercase hex."""
+    _test_only("use_own_fingerprint_for_tests")
+    if not _FINGERPRINT_HEX.fullmatch(fingerprint):
+        raise ValueError(f"use_own_fingerprint_for_tests: {fingerprint!r} is not 64 lowercase hex")
+    return _use(replace(active(), own_fingerprint=fingerprint))
+
+
+def alias_tag(tag: str, channel: Channel | None = None) -> str | None:
+    """The alias a version request for `tag` resolves first under a contract
+    with an own fingerprint, or None when it resolves `tag` alone: under the
+    v1 contract and every production channel, and for a request that is not a
+    version spelling (an arbitrary tag has no alias)."""
+    channel = channel or active()
+    if not channel.own_fingerprint or not re.fullmatch(C.SPELLING_REGEX, tag):
+        return None
+    return f"{tag}{ALIAS_SEPARATOR}{channel.own_fingerprint}"
+
+
+def visible(predicate: object, channel: Channel | None = None) -> bool:
+    """Whether a cache record (or a pre-seeded entry) whose SIGNED predicate is
+    `predicate` may answer a request under the active contract: under one with
+    an own fingerprint (the dev channel), only when the predicate's
+    `abi_fingerprint` is that fingerprint; under every other, always. A record
+    it cannot see is never returned and never kept by the monotonic rule, and
+    nothing removes or rewrites it: another SDK of another fingerprint owns it."""
+    channel = channel or active()
+    if not channel.own_fingerprint:
+        return True
+    fingerprint = predicate.get("abi_fingerprint") if isinstance(predicate, dict) else None
+    return fingerprint == f"sha256:{channel.own_fingerprint}"
+
+
 def use_dev_channel_for_tests() -> Callable[[], None]:
     """Make this TEST run speak the dev channel exactly as a user's process does
     (undoing either function above, for a test of the dev channel itself).