k-dash 0.1.0__py3-none-any.whl

k_dash/__init__.py

@@ -0,0 +1,5 @@
+"""Public k-dash API."""
+
+from .api import get, load
+
+__all__ = ["get", "load"]

k_dash/api.py

@@ -0,0 +1,77 @@
+"""Synchronous public Python load API."""
+
+from __future__ import annotations
+
+import threading
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .cache import Cache
+from .canonical import normalize_args
+from .config import load_registry_set
+from .errors import ContractError, OfflineCacheMiss
+from .project import validate_kernel_name
+from .runtime import materialize, pull_release, resolve_release
+from .target import detect_target
+from .validation import validate_host_cxx_runtime, validate_host_dependencies, validate_tvm_ffi_runtime
+
+_modules: dict[str, Any] = {}
+_module_locks: dict[str, threading.Lock] = {}
+_guard = threading.Lock()
+
+
+def get(kernel: str, *, jit_args: Mapping[str, Any] | None = None, version: str) -> Path:
+    """Resolve, materialize and return the absolute path to ``kernel.so``.
+
+    This is the download-path solver: registry / offline cache lookup, Binary
+    Miss local JIT when needed, then a stable cache path callers can load.
+    """
+    validate_kernel_name(kernel)
+    if not isinstance(version, str) or not version:
+        raise ContractError("version must be a non-empty string", stage="load")
+    if jit_args is not None and not isinstance(jit_args, Mapping):
+        raise ContractError("jit_args must be a mapping", stage="load")
+    registries = load_registry_set()
+    cache = Cache()
+    release_digest, authority = resolve_release(registries, kernel, version, cache)
+    cached_release = cache.get_release(release_digest)
+    if cached_release is None:
+        import os
+
+        if os.environ.get("K_DASH_OFFLINE") == "1":
+            raise OfflineCacheMiss(
+                "release is absent from the offline cache",
+                stage="offline",
+                context={"release_digest": release_digest},
+            )
+        release = pull_release(authority, kernel, release_digest)
+        cache.commit_release(release_digest, release.config, release.layers[0])
+        release_config = release.config
+    else:
+        release_config = cached_release[0]
+    args = normalize_args(dict(jit_args or {}), release_config["args_schema"])
+    target = detect_target()
+    _, module_path = materialize(
+        registries, authority, kernel, release_digest, args, target, cache
+    )
+    return Path(module_path).resolve()
+
+
+def load(kernel: str, *, jit_args: Mapping[str, Any] | None = None, version: str):
+    """Resolve, materialize, validate and load one TVM-FFI module."""
+    module_path = get(kernel, jit_args=jit_args, version=version)
+    key = str(module_path)
+    with _guard:
+        lock = _module_locks.setdefault(key, threading.Lock())
+    with lock:
+        if key not in _modules:
+            import tvm_ffi
+
+            build_config = json.loads(module_path.with_name("config.json").read_text())
+            validate_tvm_ffi_runtime(build_config, tvm_ffi.__version__)
+            validate_host_dependencies(build_config)
+            validate_host_cxx_runtime(build_config)
+            _modules[key] = tvm_ffi.load_module(str(module_path))
+        return _modules[key]

k_dash/artifact.py

@@ -0,0 +1,104 @@
+"""OCI release/build artifact construction and verification."""
+
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import PurePosixPath
+from typing import Any
+
+import zstandard
+
+from .canonical import build_key, canonical_json, digest_bytes, loads_no_duplicates
+from .errors import ArtifactIntegrityError
+from .model import BuildSpec
+
+OCI_MANIFEST = "application/vnd.oci.image.manifest.v1+json"
+RELEASE_TYPE = "application/vnd.k-dash.release.v1"
+BUILD_TYPE = "application/vnd.k-dash.build.v1"
+
+
+def binary_archive(kernel_so: bytes) -> bytes:
+    stream = io.BytesIO()
+    with tarfile.open(fileobj=stream, mode="w", format=tarfile.USTAR_FORMAT) as archive:
+        info = tarfile.TarInfo("kernel.so")
+        info.size = len(kernel_so)
+        info.mode = 0o755
+        info.mtime = 0
+        info.uid = info.gid = 0
+        archive.addfile(info, io.BytesIO(kernel_so))
+    return zstandard.ZstdCompressor(level=19, write_checksum=True).compress(stream.getvalue())
+
+
+def extract_binary_archive(payload: bytes) -> bytes:
+    try:
+        raw = zstandard.ZstdDecompressor().decompress(payload)
+    except zstandard.ZstdError as error:
+        raise ArtifactIntegrityError("invalid binary compression", stage="build-artifact") from error
+    with tarfile.open(fileobj=io.BytesIO(raw), mode="r:") as archive:
+        members = archive.getmembers()
+        if len(members) != 1 or members[0].name != "kernel.so" or not members[0].isfile():
+            raise ArtifactIntegrityError("binary layer must contain only kernel.so", stage="build-artifact")
+        if PurePosixPath(members[0].name).is_absolute():
+            raise ArtifactIntegrityError("absolute archive path", stage="build-artifact")
+        source = archive.extractfile(members[0])
+        assert source is not None
+        return source.read()
+
+
+def build_objects(
+    spec: BuildSpec,
+    kernel_so: bytes,
+    *,
+    provenance: dict[str, Any],
+    host_dependencies: list[dict[str, str]],
+    cxx_runtime: dict[str, Any] | None = None,
+) -> tuple[dict[str, Any], bytes, bytes, bytes, str]:
+    key = build_key(spec)
+    layer = binary_archive(kernel_so)
+    config = {
+        "protocol_version": 1,
+        "release_digest": spec.release_digest,
+        "buildspec": spec.as_dict(),
+        "build_key": key,
+        "provenance": provenance,
+        "host_dependencies": host_dependencies,
+        "cxx_runtime": cxx_runtime,
+        "kernel_so_digest": digest_bytes(kernel_so),
+        "binary": {"digest": digest_bytes(layer), "size": len(layer)},
+    }
+    config_bytes = canonical_json(config)
+    manifest = {
+        "schemaVersion": 2,
+        "mediaType": OCI_MANIFEST,
+        "artifactType": BUILD_TYPE,
+        "config": {
+            "mediaType": "application/vnd.k-dash.build.config.v1+json",
+            "digest": digest_bytes(config_bytes),
+            "size": len(config_bytes),
+        },
+        "layers": [{
+            "mediaType": "application/vnd.k-dash.binary.v1.tar+zstd",
+            "digest": digest_bytes(layer),
+            "size": len(layer),
+        }],
+    }
+    manifest_bytes = canonical_json(manifest)
+    return config, config_bytes, layer, manifest_bytes, digest_bytes(manifest_bytes)
+
+
+def parse_json_blob(data: bytes, *, stage: str) -> dict[str, Any]:
+    try:
+        value = loads_no_duplicates(data, stage=stage)
+    except (ContractError, UnicodeDecodeError) as error:
+        raise ArtifactIntegrityError("artifact JSON is invalid", stage=stage) from error
+    if not isinstance(value, dict):
+        raise ArtifactIntegrityError("artifact JSON must be an object", stage=stage)
+    return value
+
+
+def verify_descriptor(descriptor: dict[str, Any], payload: bytes, *, stage: str) -> None:
+    expected_digest = descriptor.get("digest")
+    expected_size = descriptor.get("size")
+    if digest_bytes(payload) != expected_digest or len(payload) != expected_size:
+        raise ArtifactIntegrityError("descriptor digest or size mismatch", stage=stage)

k_dash/builder.py

@@ -0,0 +1,217 @@
+"""Nix Local JIT and archive-stream Docker AOT execution."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .canonical import canonical_json
+from .errors import ContractError, KDashError
+from .model import BuildSpec
+from .project import materialize_source_tree
+
+DEFAULT_BUILDER_IMAGE = "nixos/nix:2.24.9"
+
+
+def _driver_expression(source: Path, spec: BuildSpec, system: str) -> str:
+    # Kernel flakes own and lock nixpkgs. build.nix owns its build helpers, so
+    # the Release remains self-contained and has no separate kdlib dependency.
+    return f'''let
+  source = builtins.path {{ path = {json.dumps(str(source))}; name = "kernel-source"; }};
+  flake = builtins.getFlake (
+    builtins.unsafeDiscardStringContext ("path:" + toString source)
+  );
+  system = {json.dumps(system)};
+  hasCuteDsl = builtins.hasAttr "cutedsl-toolchain" flake.inputs;
+  hasCompatNixpkgs = builtins.hasAttr "compat-nixpkgs" flake.inputs;
+  cuteDslOverlays =
+    if hasCuteDsl then [
+      (import ((builtins.getAttr "cutedsl-toolchain" flake.inputs) + "/nix-builder/overlay.nix") {{
+        builderProvenance = null;
+      }})
+    ] else [ ];
+  basePkgs = import flake.inputs.nixpkgs {{
+    inherit system;
+    config.allowUnfree = true;
+  }};
+  cudaPkgs = import flake.inputs.cuda-nixpkgs {{
+    inherit system;
+    config.allowUnfree = true;
+    overlays = cuteDslOverlays;
+  }};
+  compatPkgs = if hasCompatNixpkgs then
+    import flake.inputs.compat-nixpkgs {{
+      inherit system;
+      config.allowUnfree = true;
+    }}
+  else basePkgs;
+  manylinuxHostCc = if hasCompatNixpkgs then
+    basePkgs.wrapCCWith {{
+      cc = compatPkgs.gcc11.cc;
+      bintools = basePkgs.stdenv.cc.bintools;
+      libc = basePkgs.glibc;
+    }}
+  else basePkgs.stdenv.cc;
+  pkgs = basePkgs // {{
+    cudaPackages_12_8 = cudaPkgs.cudaPackages_12_8;
+    # GCC 11 supplies the compiler and C++ headers.  The wrapper supplies the
+    # base pin's glibc 2.27 headers, CRT and linker paths; kernel build.nix can
+    # then select a compatible dynamic libstdc++/libgcc at final link time.
+    manylinuxHostStdenv = basePkgs.overrideCC basePkgs.stdenv manylinuxHostCc;
+  }} // (if builtins.hasAttr "cudaPackages_13" cudaPkgs then {{
+    cudaPackages_13 = cudaPkgs.cudaPackages_13;
+  }} else {{ }}) // (if builtins.hasAttr "cudaPackages_13_0" cudaPkgs then {{
+    cudaPackages_13_0 = cudaPkgs.cudaPackages_13_0;
+  }} else {{ }}) // (if hasCuteDsl then {{
+    cutePythonEnv = cudaPkgs.python313.withPackages (ps: [ ps.nvidia-cutlass-dsl ]);
+  }} else {{ }});
+  buildSpec = builtins.fromJSON {json.dumps(canonical_json(spec.as_dict()).decode())};
+in import (source + "/build.nix") {{ inherit pkgs buildSpec; }}
+'''
+
+
+def _nix_system(spec: BuildSpec) -> str:
+    return {"x86_64": "x86_64-linux", "aarch64": "aarch64-linux"}[spec.target["arch"]]
+
+
+def local_jit(source: Path, spec: BuildSpec) -> tuple[bytes, dict[str, Any]]:
+    if shutil.which("nix") is None:
+        raise KDashError("Nix is unavailable after Binary Miss", stage="local-jit")
+    with tempfile.TemporaryDirectory(prefix="k-dash-jit-") as temporary:
+        temporary_path = Path(temporary)
+        expression = _driver_expression(source.resolve(), spec, _nix_system(spec))
+        expression_path = temporary_path / "driver.nix"
+        expression_path.write_text(expression)
+        environment = {
+            "PATH": os.environ.get("PATH", ""),
+            "HOME": os.environ.get("HOME", ""),
+            "NIX_CONFIG": "experimental-features = nix-command flakes\nsandbox = true\npure-eval = true",
+        }
+        timeout = int(os.environ.get("K_DASH_JIT_TIMEOUT", "1800"))
+        jobs = os.environ.get("K_DASH_NIX_MAX_JOBS", "auto")
+        try:
+            command = [
+                "nix", "build", "--no-link", "--print-out-paths", "--max-jobs", jobs,
+                "--file", str(expression_path),
+            ]
+            if os.environ.get("K_DASH_OFFLINE") == "1":
+                command.insert(2, "--offline")
+            result = subprocess.run(
+                command,
+                check=True,
+                capture_output=True,
+                text=True,
+                env=environment,
+                timeout=timeout,
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+            stderr = getattr(error, "stderr", None)
+            context = {"stderr": stderr[-4000:]} if stderr else None
+            raise KDashError(
+                "Nix Local JIT failed", stage="local-jit", context=context
+            ) from error
+        output = Path(result.stdout.strip().splitlines()[-1])
+        module = output / "kernel.so"
+        if not module.is_file() or any(path.name != "kernel.so" for path in output.iterdir()):
+            raise ContractError("build output must contain only kernel.so", stage="local-jit")
+        return module.read_bytes(), {"mode": "local-jit", "nix_output": output.name}
+
+
+def nix_aot(source: Path, spec: BuildSpec) -> tuple[bytes, dict[str, Any]]:
+    """Build inside an already isolated CI container without nested namespaces."""
+    if shutil.which("nix") is None:
+        raise KDashError("Nix is unavailable", stage="nix-aot")
+    with tempfile.TemporaryDirectory(prefix="k-dash-nix-aot-") as temporary:
+        driver = Path(temporary) / "driver.nix"
+        driver.write_text(_driver_expression(source.resolve(), spec, _nix_system(spec)))
+        environment = {
+            "PATH": os.environ.get("PATH", ""),
+            "HOME": temporary,
+            "NIX_CONFIG": "experimental-features = nix-command flakes\nsandbox = false\npure-eval = true\nbuild-users-group =\nfilter-syscalls = false",
+        }
+        try:
+            result = subprocess.run(
+                ["nix", "build", "--no-link", "--print-out-paths", "--max-jobs",
+                 os.environ.get("K_DASH_NIX_MAX_JOBS", "auto"), "--file", str(driver)],
+                check=True, stdout=subprocess.PIPE, text=True, env=environment,
+                timeout=int(os.environ.get("K_DASH_AOT_TIMEOUT", "1800")),
+            )
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as error:
+            raise KDashError("Nix AOT failed", stage="nix-aot") from error
+        output = Path(result.stdout.strip().splitlines()[-1])
+        module = output / "kernel.so"
+        if not module.is_file() or any(path.name != "kernel.so" for path in output.iterdir()):
+            raise ContractError("build output must contain only kernel.so", stage="nix-aot")
+        return module.read_bytes(), {"mode": "nix-aot", "nix_output": output.name}
+
+
+def docker_aot(
+    source: Path,
+    spec: BuildSpec,
+    *,
+    builder_image: str = DEFAULT_BUILDER_IMAGE,
+) -> tuple[bytes, dict[str, Any]]:
+    try:
+        import docker
+    except ImportError as error:
+        raise KDashError("install k-dash[build] for Docker AOT", stage="docker-aot") from error
+    client = docker.from_env()
+    try:
+        client.volumes.get("k-dash-nix-store")
+    except docker.errors.NotFound:
+        client.volumes.create(name="k-dash-nix-store", labels={"org.k-dash.cache": "nix-store"})
+    with tempfile.TemporaryDirectory(prefix="k-dash-aot-") as temporary:
+        temporary_path = Path(temporary)
+        stage = temporary_path / "work"
+        materialize_source_tree(source, stage / "source")
+        expression = _driver_expression(Path("/tmp/source"), spec, _nix_system(spec))
+        (stage / "driver.nix").write_text(expression)
+        archive = shutil.make_archive(str(temporary_path / "context"), "tar", root_dir=stage, base_dir=".")
+        container = client.containers.create(
+            builder_image,
+            command=[
+                "sh", "-lc",
+                "nix --extra-experimental-features 'nix-command flakes' build "
+                "--option sandbox true --option filter-syscalls false "
+                "--no-link --print-out-paths --file /tmp/driver.nix > /tmp/output && "
+                "cp $(tail -n1 /tmp/output)/kernel.so /tmp/kernel.so",
+            ],
+            platform="linux/amd64" if spec.target["arch"] == "x86_64" else "linux/arm64",
+            network_disabled=False,
+            user="0:0",
+            security_opt=["seccomp=unconfined"],
+            # Very large daemon defaults make Nix 2.24 close billions of FDs
+            # before exec. Bound this per-container startup work.
+            ulimits=[docker.types.Ulimit(name="nofile", soft=65536, hard=65536)],
+            volumes={"k-dash-nix-store": {"bind": "/nix", "mode": "rw"}},
+        )
+        try:
+            with open(archive, "rb") as stream:
+                if not container.put_archive("/tmp", stream):
+                    raise KDashError("failed to stream source into builder", stage="docker-aot")
+            container.start()
+            # A cold /nix volume has to fetch and unpack the whole CUDA
+            # toolchain before it ever reaches nvcc, which outlasts any timeout
+            # that is reasonable once the store is warm.
+            status = container.wait(timeout=int(os.environ.get("K_DASH_AOT_TIMEOUT", "1800")))
+            if status.get("StatusCode") != 0:
+                log = container.logs(stdout=True, stderr=True, tail=80).decode(errors="replace")
+                raise KDashError("Docker AOT failed", stage="docker-aot", context={"log": log})
+            bits, _ = container.get_archive("/tmp/kernel.so")
+            import io
+            import tarfile
+
+            with tarfile.open(fileobj=io.BytesIO(b"".join(bits)), mode="r:") as tar:
+                extracted = tar.extractfile("kernel.so")
+                if extracted is None:
+                    raise KDashError("builder returned no kernel.so", stage="docker-aot")
+                payload = extracted.read()
+            image = client.images.get(builder_image)
+            return payload, {"mode": "docker-aot", "builder_image": builder_image, "builder_digest": image.id}
+        finally:
+            container.remove(force=True)

k_dash/cache.py

@@ -0,0 +1,126 @@
+"""Content-addressed cache with per-BuildKey advisory locking."""
+
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import json
+import os
+import shutil
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from .canonical import canonical_json
+from .errors import ArtifactIntegrityError
+from .project import extract_source_archive
+
+
+class Cache:
+    def __init__(self, root: Path | None = None):
+        self.root = root or Path(os.environ.get("K_DASH_CACHE_DIR", "~/.cache/k-dash")).expanduser()
+        for child in ("releases", "builds", "resolutions", "locks", "tmp"):
+            (self.root / child).mkdir(parents=True, exist_ok=True)
+
+    def build_dir(self, build_key: str) -> Path:
+        return self.root / "builds" / build_key.removeprefix("sha256:")
+
+    def release_dir(self, digest: str) -> Path:
+        return self.root / "releases" / digest.removeprefix("sha256:")
+
+    def get_release(self, digest: str) -> tuple[dict[str, Any], bytes, Path] | None:
+        path = self.release_dir(digest)
+        config_path = path / "config.json"
+        archive_path = path / "source.tar.zst"
+        source_path = path / "source"
+        if not config_path.is_file() or not archive_path.is_file() or not source_path.is_dir():
+            return None
+        config = json.loads(config_path.read_text())
+        if config.get("source", {}).get("digest") is None:
+            raise ArtifactIntegrityError("cached Release config is incomplete", stage="cache")
+        return config, archive_path.read_bytes(), source_path
+
+    def commit_release(self, digest: str, config: dict[str, Any], source_archive: bytes) -> Path:
+        destination = self.release_dir(digest)
+        if destination.exists():
+            return destination
+        temporary = Path(tempfile.mkdtemp(prefix="release-", dir=self.root / "tmp"))
+        try:
+            (temporary / "config.json").write_bytes(canonical_json(config))
+            (temporary / "source.tar.zst").write_bytes(source_archive)
+            extract_source_archive(source_archive, temporary / "source")
+            try:
+                temporary.replace(destination)
+            except FileExistsError:
+                pass
+        finally:
+            if temporary.exists():
+                shutil.rmtree(temporary)
+        return destination
+
+    def get_build(self, build_key: str) -> tuple[dict[str, Any], Path] | None:
+        path = self.build_dir(build_key)
+        config_path = path / "config.json"
+        module_path = path / "kernel.so"
+        if not config_path.is_file() or not module_path.is_file():
+            return None
+        config = json.loads(config_path.read_text())
+        if config.get("build_key") != build_key:
+            raise ArtifactIntegrityError("cached BuildKey mismatch", stage="cache", context={"path": str(path)})
+        return config, module_path
+
+    def commit_build(self, build_key: str, config: dict[str, Any], kernel_so: bytes) -> Path:
+        destination = self.build_dir(build_key)
+        if destination.exists():
+            return destination
+        temporary = Path(tempfile.mkdtemp(prefix="build-", dir=self.root / "tmp"))
+        try:
+            (temporary / "config.json").write_bytes(canonical_json(config))
+            (temporary / "kernel.so").write_bytes(kernel_so)
+            (temporary / "kernel.so").chmod(0o755)
+            try:
+                temporary.replace(destination)
+            except FileExistsError:
+                pass
+        finally:
+            if temporary.exists():
+                shutil.rmtree(temporary)
+        return destination
+
+    @contextlib.contextmanager
+    def build_lock(self, build_key: str) -> Iterator[None]:
+        path = self.root / "locks" / (build_key.removeprefix("sha256:") + ".lock")
+        with path.open("a+b") as handle:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+    def resolution_path(self, registry: str, kernel: str, version: str) -> Path:
+        safe_version = version.replace("/", "%2F")
+        return self.root / "resolutions" / registry / kernel / f"{safe_version}.json"
+
+    def put_resolution(self, registry: str, kernel: str, version: str, digest: str) -> None:
+        path = self.resolution_path(registry, kernel, version)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_suffix(".tmp")
+        temporary.write_bytes(canonical_json({"release_digest": digest}))
+        temporary.replace(path)
+
+    def get_resolution(self, registry: str, kernel: str, version: str) -> str | None:
+        path = self.resolution_path(registry, kernel, version)
+        if not path.is_file():
+            return None
+        return json.loads(path.read_text()).get("release_digest")
+
+    def size(self) -> int:
+        return sum(path.stat().st_size for path in self.root.rglob("*") if path.is_file())
+
+    def clean(self) -> None:
+        for child in ("releases", "builds", "resolutions", "tmp"):
+            path = self.root / child
+            if path.exists():
+                shutil.rmtree(path)
+            path.mkdir(parents=True, exist_ok=True)

k_dash/canonical.py

@@ -0,0 +1,124 @@
+"""Args normalization and RFC 8785 BuildKey calculation."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import math
+from typing import Any
+
+import jsonschema
+import rfc8785
+
+from .errors import ContractError
+from .model import BuildSpec
+
+MAX_SAFE_INTEGER = (1 << 53) - 1
+
+
+def loads_no_duplicates(payload: str | bytes, *, stage: str) -> Any:
+    def pairs(pairs_value: list[tuple[str, Any]]) -> dict[str, Any]:
+        output: dict[str, Any] = {}
+        for key, value in pairs_value:
+            if key in output:
+                raise ContractError(
+                    "duplicate JSON object key",
+                    stage=stage,
+                    context={"key": key},
+                )
+            output[key] = value
+        return output
+
+    try:
+        return json.loads(payload, object_pairs_hook=pairs)
+    except json.JSONDecodeError as error:
+        raise ContractError("invalid JSON", stage=stage) from error
+
+
+def _apply_defaults(instance: Any, schema: dict[str, Any]) -> Any:
+    if isinstance(instance, dict):
+        properties = schema.get("properties", {})
+        for key, subschema in properties.items():
+            if key not in instance and "default" in subschema:
+                instance[key] = copy.deepcopy(subschema["default"])
+            if key in instance:
+                instance[key] = _apply_defaults(instance[key], subschema)
+    elif isinstance(instance, list):
+        item_schema = schema.get("items", {})
+        for index, value in enumerate(instance):
+            instance[index] = _apply_defaults(value, item_schema)
+    return instance
+
+
+def _validate_i_json(value: Any, path: str = "$") -> None:
+    if isinstance(value, bool) or value is None or isinstance(value, str):
+        return
+    if isinstance(value, int):
+        if not -MAX_SAFE_INTEGER <= value <= MAX_SAFE_INTEGER:
+            raise ContractError(
+                "integer is outside the I-JSON exact range",
+                stage="args",
+                context={"path": path, "value": value},
+            )
+        return
+    if isinstance(value, float):
+        if not math.isfinite(value) or (value == 0.0 and math.copysign(1.0, value) < 0):
+            raise ContractError(
+                "non-finite and negative-zero numbers are forbidden",
+                stage="args",
+                context={"path": path},
+            )
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            _validate_i_json(item, f"{path}[{index}]")
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise ContractError("object keys must be strings", stage="args", context={"path": path})
+            _validate_i_json(item, f"{path}.{key}")
+        return
+    raise ContractError("value is not JSON-compatible", stage="args", context={"path": path})
+
+
+def normalize_args(raw: dict[str, Any] | None, schema: dict[str, Any]) -> dict[str, Any]:
+    if raw is None:
+        raw = {}
+    if not isinstance(raw, dict):
+        raise ContractError("kernel args must be a JSON object", stage="args")
+    normalized = _apply_defaults(copy.deepcopy(raw), schema)
+    try:
+        jsonschema.Draft202012Validator(schema).validate(normalized)
+    except jsonschema.ValidationError as error:
+        raise ContractError(
+            error.message,
+            stage="args",
+            context={"path": ".".join(str(part) for part in error.absolute_path) or "$"},
+        ) from error
+    _validate_i_json(normalized)
+    return normalized
+
+
+def canonical_json(value: Any) -> bytes:
+    _validate_i_json(value)
+    try:
+        return rfc8785.dumps(value)
+    except (TypeError, ValueError) as error:
+        raise ContractError(str(error), stage="canonical-json") from error
+
+
+def digest_bytes(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def build_key(spec: BuildSpec | dict[str, Any]) -> str:
+    value = spec.as_dict() if isinstance(spec, BuildSpec) else spec
+    return digest_bytes(canonical_json(value))
+
+
+def build_tag(key: str) -> str:
+    if not key.startswith("sha256:") or len(key) != 71:
+        raise ContractError("invalid BuildKey", stage="build-key", context={"build_key": key})
+    return "build-sha256-" + key.removeprefix("sha256:")