cloudfall 0.3.0__tar.gz → 0.4.0__tar.gz

{cloudfall-0.3.0 → cloudfall-0.4.0}/CHANGELOG.md

@@ -6,6 +6,32 @@ Notable changes to Cloudfall. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-09-21
+
+### Added
+
+- Brownfield fleet reader: `cloudfall audit` and `cloudfall inventory show`
+  read the fleet from the team's own Ansible inventory, with `--inventory`
+  or from the inventory an `ansible.cfg` in the current directory names.
+  Hosts, groups and connection settings come from Ansible; a `cloudfall`
+  block per host, `cloudfall_defaults` per group and the
+  `cloudfall_server_types` catalog carry what Ansible does not model. The
+  documents are validated against the same schemas a project directory
+  gets, so `PlatformInventory` and everything built on it is unchanged
+- `cloudfall.ansible_api` is the only module that imports ansible-core. It
+  reads in process and falls back to the `ansible-inventory` command,
+  reporting which served the read
+- `cloudfall observe` collects one read-only snapshot per server through
+  the team's inventory plus an ephemeral overlay holding only the
+  `cloudfall_servers` group and the two variables the inspect role cannot
+  derive, so the audit loop closes without a Cloudfall project. Their own
+  `ansible.cfg` keeps deciding how Ansible connects; only the roles path
+  is forced. `--limit` takes an Ansible host pattern, which Ansible
+  resolves, and the run is judged against the hosts it asked for
+- `StateValidator.validate_documents` validates resource documents
+  assembled in memory, with the schemas, reference checks and error codes
+  documents on disk get
+
 ## [0.3.0] — 2026-09-20
 
 ### Removed

{cloudfall-0.3.0 → cloudfall-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cloudfall
-Version: 0.3.0
+Version: 0.4.0
 Summary: AI-native control plane for dedicated Debian application fleets
 Project-URL: Homepage, https://cloudfall.dev
 Project-URL: Repository, https://github.com/romamo/cloudfall

{cloudfall-0.3.0 → cloudfall-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cloudfall"
-version = "0.3.0"
+version = "0.4.0"
 description = "AI-native control plane for dedicated Debian application fleets"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -88,3 +88,9 @@ ignore = [
 python_version = "3.14"
 strict = true
 files = ["sdk/src", "sdk/tests", "engine/src", "engine/tests"]
+
+# ansible-core ships no type information. Only cloudfall.ansible_api imports
+# it, and it converts what it reads into typed value objects at that edge.
+[[tool.mypy.overrides]]
+module = ["ansible.*"]
+ignore_missing_imports = true

cloudfall-0.4.0/sdk/src/cloudfall/ansible_api.py

@@ -0,0 +1,356 @@
+"""The one module that imports ansible-core.
+
+ansible-core's Python API carries no stability promise, so every import of
+``ansible.*`` lives here and the rest of the SDK sees typed value objects
+instead. Reading an inventory in process costs one import (about 150 ms per
+CLI invocation) and is in memory afterwards, which matters because the
+agent's hot path reads the fleet far more often than it runs a playbook.
+
+When the in-process loader fails on an ansible-core release, the same
+function falls back to the ``ansible-inventory`` command and says so in
+``AnsibleInventory.in_process``, so a broken internal API degrades to a
+slower read rather than to no read at all.
+"""
+
+from __future__ import annotations
+
+import configparser
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+_HOSTNAME_PATTERN = re.compile(r"^[^\s]{1,253}$")
+_GROUP_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_INVENTORY_TIMEOUT_SECONDS = 120
+_META_KEY = "_meta"
+_HOSTVARS_KEY = "hostvars"
+_HOSTS_KEY = "hosts"
+_ALL_GROUP = "all"
+
+ANSIBLE_CONFIG_FILE = "ansible.cfg"
+"""Ansible's own configuration file, which names the team's inventory."""
+
+_CONFIG_SECTION = "defaults"
+_CONFIG_INVENTORY_KEY = "inventory"
+_ERROR_CONFIG_UNREADABLE = "ansible_config_unreadable"
+_ERROR_SOURCE_MISSING = "ansible_inventory_missing"
+_ERROR_INVENTORY_UNREADABLE = "ansible_inventory_unreadable"
+_ERROR_COMMAND_UNAVAILABLE = "ansible_command_unavailable"
+
+
+class AnsibleReadError(RuntimeError):
+    """Fail-fast inventory read error with a stable machine-readable code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        """Record the failure code and human-readable detail."""
+        self.code = code
+        self.detail = message
+        super().__init__(f"{code}: {message}")
+
+    def as_dict(self) -> dict[str, object]:
+        """Serialize the error envelope for system boundaries."""
+        return {
+            "status": "error",
+            "error": {"code": self.code, "message": self.detail},
+        }
+
+
+class _InProcessReadError(RuntimeError):
+    """ansible-core's Python API could not serve the read on this release."""
+
+
+@dataclass(frozen=True, slots=True)
+class InventorySource:
+    """An Ansible inventory: one file, or a directory of them."""
+
+    value: Path
+
+    def __post_init__(self) -> None:
+        """Enforce that the source exists at construction time."""
+        if not self.value.exists():
+            message = f"inventory source does not exist: {self.value}"
+            raise AnsibleReadError(_ERROR_SOURCE_MISSING, message)
+
+    @classmethod
+    def from_boundary(cls, value: object) -> InventorySource:
+        """Coerce a boundary value while keeping internal APIs strictly typed."""
+        if not isinstance(value, str | Path):
+            message = f"inventory source must be a path, got {type(value).__name__}"
+            raise TypeError(message)
+        return cls(Path(value).expanduser())
+
+    def __str__(self) -> str:
+        """Return the serialized path."""
+        return str(self.value)
+
+
+@dataclass(frozen=True, slots=True)
+class InventoryHostname:
+    """Name of a host as the team's inventory spells it."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        """Enforce one non-empty, whitespace-free token."""
+        if not _HOSTNAME_PATTERN.fullmatch(self.value):
+            message = f"inventory hostname must be one bare token: {self.value!r}"
+            raise ValueError(message)
+
+    @classmethod
+    def from_boundary(cls, value: object) -> InventoryHostname:
+        """Coerce a boundary value while keeping internal APIs strictly typed."""
+        if not isinstance(value, str):
+            message = f"inventory hostname must be a string, got {type(value).__name__}"
+            raise TypeError(message)
+        return cls(value.strip())
+
+    def __str__(self) -> str:
+        """Return the serialized name."""
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class GroupName:
+    """Name of an inventory group a host belongs to."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        """Enforce the identifier shape Ansible requires of a group."""
+        if not _GROUP_NAME_PATTERN.fullmatch(self.value):
+            message = f"group name must be an Ansible identifier: {self.value!r}"
+            raise ValueError(message)
+
+    @classmethod
+    def from_boundary(cls, value: object) -> GroupName:
+        """Coerce a boundary value while keeping internal APIs strictly typed."""
+        if not isinstance(value, str):
+            message = f"group name must be a string, got {type(value).__name__}"
+            raise TypeError(message)
+        return cls(value.strip())
+
+    def __str__(self) -> str:
+        """Return the serialized name."""
+        return self.value
+
+
+@dataclass(frozen=True, slots=True)
+class AnsibleHost:
+    """One host of the team's inventory with its merged variables."""
+
+    name: InventoryHostname
+    groups: tuple[GroupName, ...]
+    variables: Mapping[str, object]
+
+    def variable(self, name: str) -> object | None:
+        """Return one merged variable, or ``None`` when the host has none."""
+        return self.variables.get(name)
+
+
+@dataclass(frozen=True, slots=True)
+class AnsibleInventory:
+    """Every host of one inventory source, read once."""
+
+    source: InventorySource
+    hosts: tuple[AnsibleHost, ...]
+    in_process: bool
+    """The Python API served the read; ``False`` means the command did."""
+
+    def as_dict(self) -> dict[str, object]:
+        """Serialize the read for system boundaries, without variables."""
+        return {
+            "source": str(self.source),
+            "inProcess": self.in_process,
+            "hosts": [
+                {
+                    "name": str(host.name),
+                    "groups": [str(group) for group in host.groups],
+                }
+                for host in self.hosts
+            ],
+        }
+
+
+def inventory_from_config(directory: Path) -> InventorySource | None:
+    """Return the inventory an ``ansible.cfg`` in this directory names.
+
+    The team's own configuration is the only place Cloudfall looks, so a
+    brownfield repository needs no Cloudfall-side setting to be read from.
+    ``None`` means the directory is not an Ansible control repository.
+    Ansible accepts a comma-separated list of sources here; the first one
+    is the fleet, and a second source is a merge Cloudfall does not model.
+    """
+    configuration = directory / ANSIBLE_CONFIG_FILE
+    if not configuration.is_file():
+        return None
+    parser = configparser.ConfigParser()
+    try:
+        parser.read(configuration, encoding="utf-8")
+    except configparser.Error as error:
+        message = f"{configuration} is not readable as an ini file: {error}"
+        raise AnsibleReadError(_ERROR_CONFIG_UNREADABLE, message) from error
+    declared = parser.get(_CONFIG_SECTION, _CONFIG_INVENTORY_KEY, fallback="").strip()
+    if not declared:
+        return None
+    first = declared.split(",")[0].strip()
+    if not first:
+        return None
+    candidate = Path(first).expanduser()
+    if not candidate.is_absolute():
+        candidate = directory / candidate
+    return InventorySource(candidate)
+
+
+def read_inventory(
+    source: InventorySource, *, limit: str | None = None, in_process: bool = True
+) -> AnsibleInventory:
+    """Return every host of the inventory with Ansible's own precedence applied.
+
+    The Python API is tried first and the ``ansible-inventory`` command is
+    the fallback, so a release that moves the internal API costs latency
+    rather than the read. Pass ``in_process=False`` to take the command
+    without trying the API, which is what an operator does when a release
+    has broken it. ``limit`` narrows the read with Ansible's own host
+    pattern, so a caller never has to interpret one itself.
+    """
+    if not in_process:
+        return _read_via_command(source, limit)
+    try:
+        return _read_in_process(source, limit)
+    except (ImportError, _InProcessReadError):
+        return _read_via_command(source, limit)
+
+
+def _read_in_process(
+    source: InventorySource, limit: str | None = None
+) -> AnsibleInventory:
+    from ansible.errors import AnsibleError  # noqa: PLC0415 - lazy by design
+    from ansible.inventory.manager import (  # noqa: PLC0415 - lazy by design
+        InventoryManager,
+    )
+    from ansible.parsing.dataloader import (  # noqa: PLC0415 - lazy by design
+        DataLoader,
+    )
+    from ansible.vars.manager import VariableManager  # noqa: PLC0415 - lazy by design
+
+    try:
+        loader = DataLoader()
+        manager = InventoryManager(loader=loader, sources=[str(source)])
+        if limit is not None:
+            manager.subset(limit)
+        variables = VariableManager(loader=loader, inventory=manager)
+        hosts = tuple(
+            AnsibleHost(
+                name=InventoryHostname.from_boundary(host.name),
+                groups=_group_names(str(group.name) for group in host.get_groups()),
+                variables=_variables(variables.get_vars(host=host)),
+            )
+            for host in manager.get_hosts()
+        )
+    except AnsibleError as error:
+        raise _InProcessReadError(str(error)) from error
+    return AnsibleInventory(source=source, hosts=_sorted(hosts), in_process=True)
+
+
+def _read_via_command(
+    source: InventorySource, limit: str | None = None
+) -> AnsibleInventory:
+    executable = shutil.which("ansible-inventory")
+    if executable is None:
+        message = (
+            "the ansible-core Python API could not read the inventory and "
+            "ansible-inventory is not on PATH"
+        )
+        raise AnsibleReadError(_ERROR_COMMAND_UNAVAILABLE, message)
+    argv = [executable, "--inventory", str(source), "--list"]
+    if limit is not None:
+        argv.extend(("--limit", limit))
+    completed = subprocess.run(  # noqa: S603 - resolved binary, fixed arguments.
+        argv,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=_INVENTORY_TIMEOUT_SECONDS,
+    )
+    if completed.returncode != 0:
+        message = (
+            f"ansible-inventory failed with exit code {completed.returncode}: "
+            f"{completed.stderr.strip()}"
+        )
+        raise AnsibleReadError(_ERROR_INVENTORY_UNREADABLE, message)
+    return AnsibleInventory(
+        source=source,
+        hosts=_sorted(_hosts_from_listing(completed.stdout)),
+        in_process=False,
+    )
+
+
+def _hosts_from_listing(listing: str) -> tuple[AnsibleHost, ...]:
+    try:
+        parsed = json.loads(listing)
+    except json.JSONDecodeError as error:
+        message = f"ansible-inventory did not emit JSON: {error}"
+        raise AnsibleReadError(_ERROR_INVENTORY_UNREADABLE, message) from error
+    if not isinstance(parsed, dict):
+        message = "ansible-inventory did not emit an inventory object"
+        raise AnsibleReadError(_ERROR_INVENTORY_UNREADABLE, message)
+    document: Mapping[str, object] = parsed
+    hostvars = _hostvars(document)
+    groups: dict[str, list[str]] = {}
+    for key, value in document.items():
+        if key == _META_KEY or not isinstance(value, dict):
+            continue
+        members = value.get(_HOSTS_KEY)
+        if not isinstance(members, list):
+            continue
+        for member in members:
+            if isinstance(member, str):
+                groups.setdefault(member, []).append(key)
+    return tuple(
+        AnsibleHost(
+            name=InventoryHostname.from_boundary(name),
+            # `all` holds children rather than hosts in the listing, while
+            # every host belongs to it; the in-process read reports it.
+            groups=_group_names({_ALL_GROUP, *groups.get(name, [])}),
+            variables=_variables(variables),
+        )
+        for name, variables in hostvars.items()
+    )
+
+
+def _hostvars(document: Mapping[str, object]) -> Mapping[str, Mapping[str, object]]:
+    meta = document.get(_META_KEY)
+    if not isinstance(meta, dict):
+        message = "ansible-inventory emitted no _meta section"
+        raise AnsibleReadError(_ERROR_INVENTORY_UNREADABLE, message)
+    hostvars = meta.get(_HOSTVARS_KEY)
+    if not isinstance(hostvars, dict):
+        message = "ansible-inventory emitted no _meta.hostvars section"
+        raise AnsibleReadError(_ERROR_INVENTORY_UNREADABLE, message)
+    return {
+        str(name): _variables(variables)
+        for name, variables in hostvars.items()
+        if isinstance(variables, dict)
+    }
+
+
+def _variables(raw: object) -> Mapping[str, object]:
+    if not isinstance(raw, dict):
+        return {}
+    return {str(key): value for key, value in raw.items()}
+
+
+def _group_names(names: Iterable[str]) -> tuple[GroupName, ...]:
+    groups = tuple(GroupName.from_boundary(name) for name in names)
+    return tuple(sorted(groups, key=lambda group: group.value))
+
+
+def _sorted(hosts: tuple[AnsibleHost, ...]) -> tuple[AnsibleHost, ...]:
+    return tuple(sorted(hosts, key=lambda host: host.name.value))

cloudfall-0.4.0/sdk/src/cloudfall/ansible_reader.py

@@ -0,0 +1,281 @@
+"""Read a fleet from the team's own Ansible inventory.
+
+Cloudfall declares no servers in a brownfield repository. The inventory is
+the config: hosts, groups and connection settings come from Ansible, and
+everything Ansible does not model comes from a ``cloudfall`` block in the
+team's own ``host_vars``, with shared defaults in ``cloudfall_defaults``
+and the server-type catalog in ``cloudfall_server_types``.
+
+Ansible replaces rather than merges a variable of the same name, so a
+``cloudfall`` block in ``group_vars`` would silently lose to one in
+``host_vars``. The two names keep that from happening: ``cloudfall`` is
+per host, ``cloudfall_defaults`` is per group, and Cloudfall merges them
+itself with the host winning.
+
+The documents this builds are the same shape as the YAML a greenfield
+project holds, so they go through the same schemas and the same reference
+checks, and every consumer of ``PlatformInventory`` works unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from cloudfall.ansible_api import AnsibleReadError
+from cloudfall.domain import RawDocument, ResourceKind, SourceLocation
+from cloudfall.validation import SchemaCatalog, StateValidator
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+
+    from cloudfall.ansible_api import AnsibleHost, AnsibleInventory
+    from cloudfall.validation import ValidatedConfig
+
+API_VERSION = "cloudfall/v1"
+"""Envelope version of the documents the reader builds."""
+
+DECLARATION_VARIABLE = "cloudfall"
+"""Host variable holding one host's Cloudfall declaration."""
+
+DEFAULTS_VARIABLE = "cloudfall_defaults"
+"""Group variable holding declaration defaults a host may override."""
+
+CATALOG_VARIABLE = "cloudfall_server_types"
+"""Group variable holding the server-type catalog the hosts point into."""
+
+_ADDRESS_VARIABLE = "ansible_host"
+_SSH_USER_VARIABLE = "ansible_user"
+_SSH_PORT_VARIABLE = "ansible_port"
+_DEFAULT_SSH_PORT = 22
+_DESCRIPTION_FIELD = "description"
+_LABELS_FIELD = "labels"
+_HOSTNAME_FIELD = "hostname"
+_SNAKE_BOUNDARY = re.compile(r"_([a-z0-9])")
+_HOST_VARS_SUFFIXES = (".yml", ".yaml")
+
+_ERROR_DECLARATION_INVALID = "ansible_declaration_invalid"
+_ERROR_CATALOG_INVALID = "ansible_catalog_invalid"
+_ERROR_CATALOG_CONFLICT = "ansible_catalog_conflict"
+_ERROR_NO_DECLARATIONS = "ansible_no_declarations"
+
+# `labels` holds the team's own keys, which are data rather than field
+# names, so the snake-to-camel rewrite must not touch inside it.
+_OPAQUE_FIELDS = frozenset({_LABELS_FIELD})
+
+
+@dataclass(frozen=True, slots=True)
+class FleetRead:
+    """What one inventory yielded: a validated fleet, and what it skipped."""
+
+    config: ValidatedConfig
+    managed: tuple[str, ...]
+    """Hosts that carry a ``cloudfall`` declaration, in inventory order."""
+
+    unmanaged: tuple[str, ...]
+    """Hosts the inventory holds that Cloudfall was not told to manage."""
+
+    in_process: bool
+    """ansible-core's Python API served the read rather than the command."""
+
+    def as_dict(self) -> dict[str, object]:
+        """Serialize the read for system boundaries."""
+        return {
+            "status": "ok",
+            "inProcess": self.in_process,
+            "managed": list(self.managed),
+            "unmanaged": list(self.unmanaged),
+            "byKind": self.config.counts_by_kind(),
+            "resources": self.config.resource_count,
+        }
+
+
+def read_fleet(inventory: AnsibleInventory, schema_directory: Path) -> FleetRead:
+    """Turn an Ansible inventory into validated Cloudfall resources."""
+    managed = tuple(
+        host for host in inventory.hosts if _declaration(host) is not None
+    )
+    unmanaged = tuple(
+        str(host.name) for host in inventory.hosts if _declaration(host) is None
+    )
+    if not managed:
+        message = (
+            f"no host in {inventory.source} declares a `{DECLARATION_VARIABLE}` "
+            "block, so there is no fleet to read"
+        )
+        raise AnsibleReadError(_ERROR_NO_DECLARATIONS, message)
+
+    documents = [
+        *_server_type_documents(managed, inventory.source.value),
+        *(_server_document(host, inventory.source.value) for host in managed),
+    ]
+    validator = StateValidator(SchemaCatalog(schema_directory))
+    return FleetRead(
+        config=validator.validate_documents(documents),
+        managed=tuple(str(host.name) for host in managed),
+        unmanaged=unmanaged,
+        in_process=inventory.in_process,
+    )
+
+
+def _server_document(host: AnsibleHost, source: Path) -> RawDocument:
+    declaration = _declaration(host)
+    if declaration is None:  # pragma: no cover - callers filter first
+        message = f"host {host.name} declares no `{DECLARATION_VARIABLE}` block"
+        raise AnsibleReadError(_ERROR_DECLARATION_INVALID, message)
+    declared = _camelized(_merged_declaration(host, declaration))
+    spec: dict[str, object] = {
+        key: value
+        for key, value in declared.items()
+        if key not in {_DESCRIPTION_FIELD, _HOSTNAME_FIELD}
+    }
+    spec[_HOSTNAME_FIELD] = declared.get(_HOSTNAME_FIELD, str(host.name))
+    spec["address"] = _address(host)
+    spec["ssh"] = _ssh(host)
+    metadata: dict[str, object] = {"id": str(host.name)}
+    description = declared.get(_DESCRIPTION_FIELD)
+    if description is not None:
+        metadata[_DESCRIPTION_FIELD] = description
+    content = {
+        "apiVersion": API_VERSION,
+        "kind": ResourceKind.SERVER.value,
+        "metadata": metadata,
+        "spec": spec,
+    }
+    return RawDocument(content=content, source=_host_source(host, source))
+
+
+def _server_type_documents(
+    hosts: tuple[AnsibleHost, ...], source: Path
+) -> tuple[RawDocument, ...]:
+    catalog: dict[str, Mapping[str, object]] = {}
+    for host in hosts:
+        raw = host.variable(CATALOG_VARIABLE)
+        if raw is None:
+            continue
+        if not isinstance(raw, dict):
+            message = (
+                f"`{CATALOG_VARIABLE}` on host {host.name} must be a mapping of "
+                f"server type name to definition, got {type(raw).__name__}"
+            )
+            raise AnsibleReadError(_ERROR_CATALOG_INVALID, message)
+        for name, definition in raw.items():
+            if not isinstance(definition, dict):
+                message = (
+                    f"`{CATALOG_VARIABLE}.{name}` must be a mapping, got "
+                    f"{type(definition).__name__}"
+                )
+                raise AnsibleReadError(_ERROR_CATALOG_INVALID, message)
+            identifier = str(name)
+            existing = catalog.get(identifier)
+            if existing is not None and existing != definition:
+                message = (
+                    f"server type {identifier} is defined differently for "
+                    f"host {host.name} than for an earlier host; one catalog "
+                    "must describe the fleet"
+                )
+                raise AnsibleReadError(_ERROR_CATALOG_CONFLICT, message)
+            catalog[identifier] = definition
+    return tuple(
+        RawDocument(
+            content=_server_type_content(identifier, catalog[identifier]),
+            source=SourceLocation(path=source, document_number=0),
+        )
+        for identifier in sorted(catalog)
+    )
+
+
+def _server_type_content(
+    identifier: str, definition: Mapping[str, object]
+) -> Mapping[str, object]:
+    declared = _camelized(definition)
+    spec = {
+        key: value for key, value in declared.items() if key != _DESCRIPTION_FIELD
+    }
+    metadata: dict[str, object] = {"id": identifier}
+    description = declared.get(_DESCRIPTION_FIELD)
+    if description is not None:
+        metadata[_DESCRIPTION_FIELD] = description
+    return {
+        "apiVersion": API_VERSION,
+        "kind": ResourceKind.HOST_PROFILE.value,
+        "metadata": metadata,
+        "spec": spec,
+    }
+
+
+def _declaration(host: AnsibleHost) -> Mapping[str, object] | None:
+    raw = host.variable(DECLARATION_VARIABLE)
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        message = (
+            f"`{DECLARATION_VARIABLE}` on host {host.name} must be a mapping, "
+            f"got {type(raw).__name__}"
+        )
+        raise AnsibleReadError(_ERROR_DECLARATION_INVALID, message)
+    return {str(key): value for key, value in raw.items()}
+
+
+def _merged_declaration(
+    host: AnsibleHost, declaration: Mapping[str, object]
+) -> Mapping[str, object]:
+    defaults = host.variable(DEFAULTS_VARIABLE)
+    if defaults is None:
+        return declaration
+    if not isinstance(defaults, dict):
+        message = (
+            f"`{DEFAULTS_VARIABLE}` reaching host {host.name} must be a "
+            f"mapping, got {type(defaults).__name__}"
+        )
+        raise AnsibleReadError(_ERROR_DECLARATION_INVALID, message)
+    merged = {str(key): value for key, value in defaults.items()}
+    merged.update(declaration)
+    return merged
+
+
+def _address(host: AnsibleHost) -> object:
+    declared = host.variable(_ADDRESS_VARIABLE)
+    return declared if declared is not None else str(host.name)
+
+
+def _ssh(host: AnsibleHost) -> Mapping[str, object]:
+    user = host.variable(_SSH_USER_VARIABLE)
+    port = host.variable(_SSH_PORT_VARIABLE)
+    ssh: dict[str, object] = {"port": port if port is not None else _DEFAULT_SSH_PORT}
+    if user is not None:
+        ssh["user"] = user
+    return ssh
+
+
+def _host_source(host: AnsibleHost, source: Path) -> SourceLocation:
+    """Point errors at the host's own file when the inventory has one."""
+    for suffix in _HOST_VARS_SUFFIXES:
+        candidate = source / "host_vars" / f"{host.name}{suffix}"
+        if candidate.is_file():
+            return SourceLocation(path=candidate, document_number=1)
+    return SourceLocation(path=source, document_number=0)
+
+
+def _camelized(value: Mapping[str, object]) -> Mapping[str, object]:
+    """Rewrite Ansible's snake_case field names as the schemas' camelCase."""
+    return {
+        _camel(str(key)): _camelized_value(str(key), item)
+        for key, item in value.items()
+    }
+
+
+def _camelized_value(key: str, value: object) -> object:
+    if key in _OPAQUE_FIELDS:
+        return value
+    if isinstance(value, dict):
+        return _camelized({str(item): entry for item, entry in value.items()})
+    if isinstance(value, list):
+        return [_camelized_value(key, item) for item in value]
+    return value
+
+
+def _camel(name: str) -> str:
+    return _SNAKE_BOUNDARY.sub(lambda match: match.group(1).upper(), name)