dpone-airflow-pack 0.44.0__tar.gz

dpone_airflow_pack-0.44.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: dpone-airflow-pack
+Version: 0.44.0
+Summary: Lightweight Airflow scheduler-side pack provider for dpone GitOps workloads
+Keywords: airflow,gitops,data-engineering,scheduler,kubernetes
+Author: PaulKov
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Maintainer: PaulKov
+Requires-Python: >=3.11, <3.13
+Project-URL: Homepage, https://github.com/PaulKov/dpone
+Project-URL: Repository, https://github.com/PaulKov/dpone
+Project-URL: Issues, https://github.com/PaulKov/dpone/issues
+Project-URL: Documentation, https://paulkov.github.io/dpone/
+Description-Content-Type: text/markdown
+
+# dpone-airflow-pack
+
+`dpone-airflow-pack` is the lightweight Airflow scheduler/webserver provider for dpone GitOps packs.
+
+It only reads a static `airflow-pack.json` and builds visible Airflow/Kubernetes tasks. It does not import the full
+`dpone` runtime and intentionally contains no source/sink/native transfer dependencies such as ClickHouse, MSSQL,
+`pyodbc`, pandas, polars, or ConnectorX.
+
+Recommended Airflow DAG import:
+
+```python
+from dpone_airflow_pack import build_dpone_gitops_task_group_from_pack
+```
+
+The full `dpone[full,accel]` package belongs in the KPO runtime image, not in the scheduler image.

dpone_airflow_pack-0.44.0/README.md

@@ -0,0 +1,15 @@
+# dpone-airflow-pack
+
+`dpone-airflow-pack` is the lightweight Airflow scheduler/webserver provider for dpone GitOps packs.
+
+It only reads a static `airflow-pack.json` and builds visible Airflow/Kubernetes tasks. It does not import the full
+`dpone` runtime and intentionally contains no source/sink/native transfer dependencies such as ClickHouse, MSSQL,
+`pyodbc`, pandas, polars, or ConnectorX.
+
+Recommended Airflow DAG import:
+
+```python
+from dpone_airflow_pack import build_dpone_gitops_task_group_from_pack
+```
+
+The full `dpone[full,accel]` package belongs in the KPO runtime image, not in the scheduler image.

dpone_airflow_pack-0.44.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["uv_build>=0.9.18,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "dpone-airflow-pack"
+version = "0.44.0"
+description = "Lightweight Airflow scheduler-side pack provider for dpone GitOps workloads"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+license = "Apache-2.0"
+authors = [{ name = "PaulKov" }]
+maintainers = [{ name = "PaulKov" }]
+keywords = ["airflow", "gitops", "data-engineering", "scheduler", "kubernetes"]
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Database",
+  "Topic :: System :: Distributed Computing",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/PaulKov/dpone"
+Repository = "https://github.com/PaulKov/dpone"
+Issues = "https://github.com/PaulKov/dpone/issues"
+Documentation = "https://paulkov.github.io/dpone/"

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/__init__.py

@@ -0,0 +1,20 @@
+"""Lightweight Airflow-side helpers for consuming dpone GitOps packs."""
+
+from dpone_airflow_pack.pack_tasks import build_dpone_gitops_task_group_from_pack, load_dpone_airflow_pack
+from dpone_airflow_pack.runtime_adapter import (
+    DponeAirflowArtifactError,
+    DponeAirflowContractError,
+    build_dpone_gitops_task_from_artifacts,
+    load_dpone_kpo_kwargs,
+    validate_dpone_artifacts,
+)
+
+__all__ = [
+    "DponeAirflowArtifactError",
+    "DponeAirflowContractError",
+    "build_dpone_gitops_task_group_from_pack",
+    "build_dpone_gitops_task_from_artifacts",
+    "load_dpone_airflow_pack",
+    "load_dpone_kpo_kwargs",
+    "validate_dpone_artifacts",
+]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/connection_projection.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Protocol
+from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
+
+
+class ConnectionUriReader(Protocol):
+    def read_uri(self, connection_id: str) -> str: ...
+
+
+class AirflowBaseHookConnectionReader:
+    """Read Airflow connection URIs lazily at task execution time."""
+
+    def read_uri(self, connection_id: str) -> str:
+        from airflow.hooks.base import BaseHook
+
+        return BaseHook.get_connection(connection_id).get_uri()
+
+
+class RuntimeAirflowConnectionUriReader:
+    def __init__(self, *, reader: ConnectionUriReader, scheme_overrides: Mapping[str, str]) -> None:
+        self._reader = reader
+        self._scheme_overrides = dict(scheme_overrides)
+
+    def read_uri(self, connection_id: str) -> str:
+        uri = self._reader.read_uri(connection_id)
+        scheme = self._scheme_overrides.get(connection_id)
+        return replace_uri_scheme(uri, scheme) if scheme else uri
+
+
+class UnsafeAirflowConnectionEnvBuilder:
+    """Build AIRFLOW_CONN_* values from Airflow connections.
+
+    This is intentionally an execution-time adapter, not a scheduler parse-time
+    reader, so DAG parsing never touches secrets.
+    """
+
+    def __init__(self, *, reader: ConnectionUriReader) -> None:
+        self._reader = reader
+
+    def build(self, connection_ids: Sequence[str]) -> dict[str, str]:
+        return {
+            airflow_conn_env_name(connection_id): self._reader.read_uri(connection_id)
+            for connection_id in connection_ids
+        }
+
+
+def airflow_conn_env_name(connection_id: str) -> str:
+    return "AIRFLOW_CONN_" + "".join(ch if ch.isalnum() else "_" for ch in connection_id.upper())
+
+
+def apply_database_overrides(env_vars: Mapping[str, str], database_overrides: Mapping[str, str]) -> dict[str, str]:
+    patched = dict(env_vars)
+    for connection_id, database in database_overrides.items():
+        env_name = airflow_conn_env_name(connection_id)
+        if env_name in patched:
+            patched[env_name] = replace_uri_database(patched[env_name], database)
+    return patched
+
+
+def apply_query_overrides(
+    env_vars: Mapping[str, str],
+    query_overrides: Mapping[str, Mapping[str, str]],
+) -> dict[str, str]:
+    patched = dict(env_vars)
+    for connection_id, values in query_overrides.items():
+        env_name = airflow_conn_env_name(connection_id)
+        if env_name in patched:
+            patched[env_name] = merge_uri_query(patched[env_name], values)
+    return patched
+
+
+def replace_uri_database(uri: str, database: str) -> str:
+    normalized = str(database or "").strip()
+    if not normalized:
+        raise ValueError("Runtime database override must be non-empty")
+    parts = urlsplit(uri)
+    return urlunsplit((parts.scheme, parts.netloc, f"/{quote(normalized, safe='')}", parts.query, parts.fragment))
+
+
+def replace_uri_scheme(uri: str, scheme: str) -> str:
+    normalized = str(scheme or "").strip()
+    if not normalized:
+        raise ValueError("Runtime scheme override must be non-empty")
+    parts = urlsplit(uri)
+    return urlunsplit((normalized, parts.netloc, parts.path, parts.query, parts.fragment))
+
+
+def merge_uri_query(uri: str, values: Mapping[str, str]) -> str:
+    normalized = {str(key): str(value) for key, value in values.items() if str(key) and value not in (None, "")}
+    parts = urlsplit(uri)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    query.update(normalized)
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), parts.fragment))
+
+
+__all__ = [
+    "AirflowBaseHookConnectionReader",
+    "ConnectionUriReader",
+    "RuntimeAirflowConnectionUriReader",
+    "UnsafeAirflowConnectionEnvBuilder",
+    "airflow_conn_env_name",
+    "apply_database_overrides",
+    "apply_query_overrides",
+    "merge_uri_query",
+    "replace_uri_database",
+    "replace_uri_scheme",
+]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/operators.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from dpone_airflow_pack.connection_projection import (
+    AirflowBaseHookConnectionReader,
+    ConnectionUriReader,
+    RuntimeAirflowConnectionUriReader,
+    UnsafeAirflowConnectionEnvBuilder,
+    apply_database_overrides,
+    apply_query_overrides,
+)
+from dpone_airflow_pack.xcom_sidecar import XComSidecarRuntimeConfig, pin_xcom_sidecar_image
+
+try:
+    from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
+except Exception:  # pragma: no cover - local tests may not have Airflow installed.
+
+    class KubernetesPodOperator:  # type: ignore[no-redef]
+        def __init__(self, **kwargs: Any) -> None:
+            self.kwargs = kwargs
+            self.do_xcom_push = bool(kwargs.get("do_xcom_push", False))
+            self.env_vars = kwargs.get("env_vars")
+
+        def build_pod_request_obj(self, context: Any | None = None) -> Any:
+            return self.kwargs.get("full_pod_spec")
+
+        def execute(self, context: Any) -> Any:
+            return {"kind": "dpone.airflow_fallback_kpo_execute", "task_id": self.kwargs.get("task_id")}
+
+
+UNSAFE_AIRFLOW_CONNECTION_ENV_ANNOTATION = "dpone.dev/unsafe-airflow-connection-env"
+UNSAFE_AIRFLOW_CONNECTION_ENV_VALUE = "non-prod-only"
+
+
+class PinnedXComSidecarKubernetesPodOperator(KubernetesPodOperator):  # type: ignore[misc,valid-type]
+    def __init__(self, *, xcom_sidecar: XComSidecarRuntimeConfig | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.xcom_sidecar = xcom_sidecar or XComSidecarRuntimeConfig()
+
+    def build_pod_request_obj(self, context: Any | None = None) -> Any:
+        pod = super().build_pod_request_obj(context=context)
+        if getattr(self, "do_xcom_push", False):
+            pin_xcom_sidecar_image(pod, self.xcom_sidecar.image)
+        return pod
+
+
+class UnsafeAirflowConnectionEnvKubernetesPodOperator(PinnedXComSidecarKubernetesPodOperator):
+    """Inject Airflow Connection URIs into pod env at execution time.
+
+    This non-production adapter is useful while a platform moves from Airflow
+    Connection projection to Secret/Vault projection. It never reads connection
+    values during DAG parse.
+    """
+
+    def __init__(
+        self,
+        *,
+        unsafe_airflow_connection_ids: Sequence[str],
+        unsafe_connection_reader: ConnectionUriReader | None = None,
+        unsafe_runtime_database_overrides: Mapping[str, str] | None = None,
+        unsafe_runtime_query_overrides: Mapping[str, Mapping[str, str]] | None = None,
+        unsafe_runtime_scheme_overrides: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.unsafe_airflow_connection_ids = tuple(unsafe_airflow_connection_ids)
+        self.unsafe_runtime_database_overrides = dict(unsafe_runtime_database_overrides or {})
+        self.unsafe_runtime_query_overrides = {
+            connection_id: dict(values) for connection_id, values in dict(unsafe_runtime_query_overrides or {}).items()
+        }
+        self.unsafe_runtime_scheme_overrides = dict(unsafe_runtime_scheme_overrides or {})
+        self._unsafe_connection_reader = unsafe_connection_reader
+
+    def execute(self, context: Any) -> Any:
+        builder = UnsafeAirflowConnectionEnvBuilder(reader=self._reader())
+        direct_env = apply_query_overrides(
+            apply_database_overrides(
+                builder.build(self.unsafe_airflow_connection_ids),
+                self.unsafe_runtime_database_overrides,
+            ),
+            self.unsafe_runtime_query_overrides,
+        )
+        self.env_vars = merge_env_vars(getattr(self, "env_vars", None), direct_env)
+        return super().execute(context)
+
+    def _reader(self) -> ConnectionUriReader:
+        reader = self._unsafe_connection_reader or AirflowBaseHookConnectionReader()
+        if not self.unsafe_runtime_scheme_overrides:
+            return reader
+        return RuntimeAirflowConnectionUriReader(reader=reader, scheme_overrides=self.unsafe_runtime_scheme_overrides)
+
+
+def merge_env_vars(existing: object, injected: Mapping[str, str]) -> object:
+    if not existing:
+        return dict(injected)
+    if isinstance(existing, Mapping):
+        merged = dict(existing)
+        merged.update(injected)
+        return merged
+    if isinstance(existing, list):
+        injected_names = set(injected)
+        preserved = [env_var for env_var in existing if getattr(env_var, "name", None) not in injected_names]
+        return [*preserved, *[_new_env_var(name, value) for name, value in injected.items()]]
+    raise TypeError(f"Unsupported env_vars type for unsafe Airflow env injection: {type(existing)!r}")
+
+
+def _new_env_var(name: str, value: str) -> object:
+    try:
+        from kubernetes.client import models as k8s
+    except Exception:  # pragma: no cover
+        return {"name": name, "value": value}
+    return k8s.V1EnvVar(name=name, value=value)
+
+
+__all__ = [
+    "PinnedXComSidecarKubernetesPodOperator",
+    "UNSAFE_AIRFLOW_CONNECTION_ENV_ANNOTATION",
+    "UNSAFE_AIRFLOW_CONNECTION_ENV_VALUE",
+    "UnsafeAirflowConnectionEnvKubernetesPodOperator",
+    "merge_env_vars",
+]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/outcome.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from dpone_airflow_pack.outcome_gate import GitOpsAirflowOutcomeGateEvaluator
+
+
+def evaluate_pack_outcome(
+    *, upstream_task_id: str, required_status: str = "passed", ti: Any = None, **_: Any
+) -> dict[str, Any]:
+    """Evaluate the XCom summary produced by a dpone runtime KPO."""
+
+    summary = _pull_summary(ti=ti, upstream_task_id=upstream_task_id)
+    report = GitOpsAirflowOutcomeGateEvaluator().evaluate(
+        xcom_summary_path=f"xcom://{upstream_task_id}",
+        xcom_summary=summary,
+        required_status=required_status,
+    )
+    payload = report.to_jsonable()
+    if not report.passed:
+        raise RuntimeError(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+    return payload
+
+
+def _pull_summary(*, ti: Any, upstream_task_id: str) -> Mapping[str, Any]:
+    if ti is None or not hasattr(ti, "xcom_pull"):
+        raise RuntimeError("Airflow task instance with xcom_pull is required to evaluate dpone outcome")
+    raw_summary = ti.xcom_pull(task_ids=upstream_task_id)
+    if isinstance(raw_summary, Mapping):
+        return raw_summary
+    if isinstance(raw_summary, str):
+        payload = json.loads(raw_summary)
+        if isinstance(payload, Mapping):
+            return payload
+    raise RuntimeError(f"dpone runtime task `{upstream_task_id}` did not return a JSON object XCom summary")
+
+
+__all__ = ["evaluate_pack_outcome"]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/outcome_gate.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+AIRFLOW_OUTCOME_STRICT_FAIL = "strict_fail"
+AIRFLOW_OUTCOME_XCOM_THEN_GATE = "xcom_then_gate"
+AIRFLOW_OUTCOME_MODES = (AIRFLOW_OUTCOME_STRICT_FAIL, AIRFLOW_OUTCOME_XCOM_THEN_GATE)
+_OUTCOME_SOURCE = "dpone airflow-pack outcome-gate"
+
+
+@dataclass(frozen=True, slots=True)
+class AirflowPackIssue:
+    code: str
+    message: str = ""
+    path: str = ""
+    source: str = _OUTCOME_SOURCE
+
+    def to_jsonable(self) -> dict[str, str]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "path": self.path,
+            "source": self.source,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class GitOpsAirflowOutcomeGateReport:
+    xcom_summary_path: str
+    required_status: str
+    status: str
+    passed: bool
+    run_spec_path: str = ""
+    runtime_evidence_path: str = ""
+    runtime_evidence_sha256: str | None = None
+    failed_step: str | None = None
+    step_counts: dict[str, int] | None = None
+    warnings: tuple[AirflowPackIssue, ...] = ()
+    blockers: tuple[AirflowPackIssue, ...] = ()
+    kind: str = "gitops.airflow_outcome_gate"
+    schema_version: str = "1"
+    producer: str = _OUTCOME_SOURCE
+
+    def to_jsonable(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "kind": self.kind,
+            "schema_version": self.schema_version,
+            "producer": self.producer,
+            "xcom_summary_path": self.xcom_summary_path,
+            "required_status": self.required_status,
+            "status": self.status,
+            "passed": self.passed,
+            "run_spec_path": self.run_spec_path,
+            "runtime_evidence_path": self.runtime_evidence_path,
+            "failed_step": self.failed_step,
+            "warnings": [warning.to_jsonable() for warning in self.warnings],
+            "blockers": [blocker.to_jsonable() for blocker in self.blockers],
+        }
+        if self.runtime_evidence_sha256 is not None:
+            payload["runtime_evidence_sha256"] = self.runtime_evidence_sha256
+        if self.step_counts is not None:
+            payload["step_counts"] = dict(self.step_counts)
+        return payload
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_jsonable(), ensure_ascii=False, indent=2) + "\n"
+
+
+class GitOpsAirflowOutcomeGateEvaluator:
+    """Evaluate a final Airflow XCom summary without importing full dpone."""
+
+    def evaluate(
+        self,
+        *,
+        xcom_summary_path: str,
+        xcom_summary: Mapping[str, Any],
+        required_status: str = "passed",
+    ) -> GitOpsAirflowOutcomeGateReport:
+        normalized_required = _text(required_status) or "passed"
+        status = _text(xcom_summary.get("status")) or "unknown"
+        blockers = (
+            *_kind_blockers(path=xcom_summary_path, summary=xcom_summary),
+            *_status_blockers(
+                path=xcom_summary_path,
+                status=status,
+                required_status=normalized_required,
+            ),
+            *_issues(xcom_summary.get("blockers")),
+        )
+        return GitOpsAirflowOutcomeGateReport(
+            xcom_summary_path=xcom_summary_path,
+            required_status=normalized_required,
+            status=status,
+            passed=not blockers,
+            run_spec_path=_text(xcom_summary.get("run_spec_path")),
+            runtime_evidence_path=_text(xcom_summary.get("runtime_evidence_path")),
+            runtime_evidence_sha256=_optional_text(xcom_summary.get("runtime_evidence_sha256")),
+            failed_step=_optional_text(xcom_summary.get("failed_step")),
+            step_counts=_step_counts(xcom_summary.get("step_counts")),
+            blockers=blockers,
+        )
+
+
+def normalize_airflow_outcome_mode(raw_mode: object) -> str:
+    mode = _text(raw_mode) or AIRFLOW_OUTCOME_STRICT_FAIL
+    return mode if mode in AIRFLOW_OUTCOME_MODES else AIRFLOW_OUTCOME_STRICT_FAIL
+
+
+def airflow_outcome_mode_names() -> tuple[str, ...]:
+    return AIRFLOW_OUTCOME_MODES
+
+
+def _kind_blockers(*, path: str, summary: Mapping[str, Any]) -> tuple[AirflowPackIssue, ...]:
+    if summary.get("kind") == "gitops.airflow_xcom_summary":
+        return ()
+    return (
+        AirflowPackIssue(
+            code="airflow_outcome_kind_invalid",
+            message="XCom summary kind must be gitops.airflow_xcom_summary",
+            path=path,
+        ),
+    )
+
+
+def _status_blockers(*, path: str, status: str, required_status: str) -> tuple[AirflowPackIssue, ...]:
+    if status == required_status:
+        return ()
+    return (
+        AirflowPackIssue(
+            code="airflow_outcome_failed",
+            message=f"Airflow XCom outcome status is `{status}`, expected `{required_status}`",
+            path=path,
+        ),
+    )
+
+
+def _issues(raw_items: object) -> tuple[AirflowPackIssue, ...]:
+    if not isinstance(raw_items, list):
+        return ()
+    issues: list[AirflowPackIssue] = []
+    for raw_item in raw_items:
+        if not isinstance(raw_item, Mapping):
+            continue
+        code = _text(raw_item.get("code"))
+        if code:
+            issues.append(
+                AirflowPackIssue(
+                    code=code,
+                    message=_text(raw_item.get("message")),
+                    path=_text(raw_item.get("path")),
+                    source=_text(raw_item.get("source")) or "dpone airflow-pack runtime",
+                )
+            )
+    return tuple(issues)
+
+
+def _step_counts(value: object) -> dict[str, int] | None:
+    if not isinstance(value, Mapping):
+        return None
+    counts: dict[str, int] = {}
+    for key, raw_count in value.items():
+        if isinstance(raw_count, bool) or not isinstance(raw_count, int):
+            continue
+        counts[str(key)] = raw_count
+    return counts
+
+
+def _optional_text(value: object) -> str | None:
+    text = _text(value)
+    return text or None
+
+
+def _text(value: object) -> str:
+    return str(value or "").strip()
+
+
+__all__ = [
+    "AIRFLOW_OUTCOME_MODES",
+    "AIRFLOW_OUTCOME_STRICT_FAIL",
+    "AIRFLOW_OUTCOME_XCOM_THEN_GATE",
+    "AirflowPackIssue",
+    "GitOpsAirflowOutcomeGateEvaluator",
+    "GitOpsAirflowOutcomeGateReport",
+    "airflow_outcome_mode_names",
+    "normalize_airflow_outcome_mode",
+]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/pack_tasks.py

@@ -0,0 +1,238 @@
+"""Build Airflow tasks from one compact dpone GitOps pack."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+from dpone_airflow_pack.operators import (
+    PinnedXComSidecarKubernetesPodOperator,
+    UnsafeAirflowConnectionEnvKubernetesPodOperator,
+)
+from dpone_airflow_pack.outcome import evaluate_pack_outcome
+from dpone_airflow_pack.runtime_adapter import DponeAirflowContractError
+from dpone_airflow_pack.xcom_sidecar import XComSidecarRuntimeConfig
+
+_CONTRACT_OWNED_FIELDS = frozenset({"cmds", "arguments", "image", "namespace", "full_pod_spec", "do_xcom_push"})
+_PACK_METADATA_FIELDS = frozenset({"outcome_mode", "resources_profile"})
+
+
+def load_dpone_airflow_pack(pack_path: str | Path) -> dict[str, Any]:
+    """Load and validate a compact `gitops.airflow_pack` JSON file."""
+
+    path = Path(pack_path)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise DponeAirflowContractError(
+            f"dpone Airflow pack is missing: {path}",
+            blockers=({"code": "airflow_pack_missing", "path": str(path), "message": "Pack file does not exist"},),
+        ) from exc
+    except json.JSONDecodeError as exc:
+        raise DponeAirflowContractError(
+            f"dpone Airflow pack is invalid JSON: {path}",
+            blockers=({"code": "airflow_pack_json_invalid", "path": str(path), "message": exc.msg},),
+        ) from exc
+    if not isinstance(payload, dict) or payload.get("kind") != "gitops.airflow_pack":
+        raise DponeAirflowContractError(
+            f"dpone Airflow pack has invalid kind: {path}",
+            blockers=(
+                {"code": "airflow_pack_kind_invalid", "path": str(path), "message": "Expected gitops.airflow_pack"},
+            ),
+        )
+    if not isinstance(payload.get("kpo_kwargs"), dict):
+        raise DponeAirflowContractError(
+            f"dpone Airflow pack has no kpo_kwargs: {path}",
+            blockers=(
+                {"code": "airflow_pack_kpo_kwargs_missing", "path": str(path), "message": "kpo_kwargs is required"},
+            ),
+        )
+    return payload
+
+
+def build_dpone_gitops_task_group_from_pack(
+    pack_path: str | Path,
+    *,
+    dag: Any = None,
+    operator_overrides: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build compact dpone Airflow tasks from one static pack.
+
+    The helper intentionally performs no manifest parsing, GitOps rendering,
+    Kubernetes API calls, or network I/O at Airflow parse time.
+    """
+
+    pack = load_dpone_airflow_pack(pack_path)
+    kwargs = _runtime_operator_kwargs(pack)
+    kwargs["do_xcom_push"] = True
+    kwargs.update(_safe_overrides(operator_overrides))
+    step_tasks = _hook_step_tasks(pack=pack, dag=dag, operator_overrides=operator_overrides)
+    runtime = _operator_class(pack)(dag=dag, **_operator_init_kwargs(pack, kwargs))
+    tasks = {**step_tasks, "dpone_runtime": runtime}
+    _chain_pack_steps(pack, tasks)
+    for terminal in _terminal_hook_task_ids(pack):
+        _chain(tasks[terminal], runtime)
+    outcome = _outcome_task(pack=pack, dag=dag, upstream_task_id=str(kwargs["task_id"]))
+    if outcome is not None:
+        tasks["outcome_gate"] = outcome
+        _chain(runtime, outcome)
+    return tasks
+
+
+def _operator_kwargs(raw_kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in dict(raw_kwargs).items() if key not in _PACK_METADATA_FIELDS}
+
+
+def _runtime_operator_kwargs(pack: Mapping[str, Any]) -> dict[str, Any]:
+    kwargs = _operator_kwargs(pack["kpo_kwargs"])
+    command = str(pack.get("runtime_command") or "").strip()
+    if command:
+        kwargs["cmds"] = ["/bin/sh", "-ec"]
+        kwargs["arguments"] = [command]
+    pod_spec = pack.get("pod_spec")
+    if isinstance(pod_spec, Mapping):
+        kwargs["full_pod_spec"] = _deserialize_pod_spec(pod_spec)
+    return kwargs
+
+
+def _hook_step_tasks(
+    *,
+    pack: Mapping[str, Any],
+    dag: Any,
+    operator_overrides: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    tasks: dict[str, Any] = {}
+    for step in _pack_steps(pack):
+        if step.get("phase") != "pre_hook":
+            continue
+        kwargs = _runtime_operator_kwargs(pack)
+        kwargs["task_id"] = str(step["name"])
+        kwargs["name"] = str(step["name"]).replace("_", "-")
+        kwargs["cmds"] = ["/bin/sh", "-ec"]
+        kwargs["arguments"] = [str(step["command"])]
+        kwargs["do_xcom_push"] = False
+        if isinstance(kwargs.get("full_pod_spec"), Mapping):
+            kwargs["full_pod_spec"] = _pod_spec_for_step(kwargs["full_pod_spec"], step_name=str(step["name"]))
+        kwargs.update(_safe_overrides(operator_overrides))
+        tasks[str(step["name"])] = _operator_class(pack)(dag=dag, **_operator_init_kwargs(pack, kwargs))
+    return tasks
+
+
+def _operator_class(pack: Mapping[str, Any]) -> type[Any]:
+    projection = _mapping(pack.get("connection_projection"))
+    if projection.get("mode") == "unsafe_airflow_env":
+        return UnsafeAirflowConnectionEnvKubernetesPodOperator
+    return PinnedXComSidecarKubernetesPodOperator
+
+
+def _operator_init_kwargs(pack: Mapping[str, Any], kwargs: Mapping[str, Any]) -> dict[str, Any]:
+    init_kwargs = dict(kwargs)
+    xcom = _mapping(pack.get("xcom"))
+    if xcom.get("sidecar_image"):
+        init_kwargs["xcom_sidecar"] = XComSidecarRuntimeConfig(image=str(xcom["sidecar_image"]))
+    projection = _mapping(pack.get("connection_projection"))
+    if projection.get("mode") == "unsafe_airflow_env":
+        init_kwargs.update(
+            {
+                "unsafe_airflow_connection_ids": tuple(
+                    str(item) for item in _sequence(projection.get("connection_ids"))
+                ),
+                "unsafe_runtime_database_overrides": _string_mapping(projection.get("database_overrides")),
+                "unsafe_runtime_query_overrides": _nested_string_mapping(projection.get("query_overrides")),
+                "unsafe_runtime_scheme_overrides": _string_mapping(projection.get("scheme_overrides")),
+            }
+        )
+    return init_kwargs
+
+
+def _pod_spec_for_step(pod_spec: Mapping[str, Any], *, step_name: str) -> dict[str, Any]:
+    payload = deepcopy(dict(pod_spec))
+    metadata = payload.setdefault("metadata", {})
+    if isinstance(metadata, dict):
+        metadata["name"] = str(metadata.get("name") or "dpone").rstrip("-") + "-" + step_name.replace("_", "-")
+    return payload
+
+
+def _outcome_task(*, pack: Mapping[str, Any], dag: Any, upstream_task_id: str) -> Any | None:
+    outcome = _mapping(pack.get("outcome_gate"))
+    if not outcome:
+        return None
+    from airflow.providers.standard.operators.python import PythonOperator
+
+    return PythonOperator(
+        dag=dag,
+        task_id=str(outcome.get("task_id") or f"{upstream_task_id}__outcome_gate"),
+        python_callable=evaluate_pack_outcome,
+        op_kwargs={
+            "upstream_task_id": upstream_task_id,
+            "required_status": str(outcome.get("required_status") or "passed"),
+        },
+    )
+
+
+def _safe_overrides(overrides: Mapping[str, Any] | None) -> dict[str, Any]:
+    clean = dict(overrides or {})
+    forbidden = sorted(_CONTRACT_OWNED_FIELDS.intersection(clean))
+    if forbidden:
+        raise ValueError(f"operator_overrides cannot replace compact pack-owned fields: {', '.join(forbidden)}")
+    return clean
+
+
+def _mapping(value: object) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _sequence(value: object) -> tuple[object, ...]:
+    return tuple(value) if isinstance(value, list | tuple) else ()
+
+
+def _string_mapping(value: object) -> dict[str, str]:
+    return {str(key): str(item) for key, item in _mapping(value).items()}
+
+
+def _nested_string_mapping(value: object) -> dict[str, dict[str, str]]:
+    return {str(key): _string_mapping(item) for key, item in _mapping(value).items()}
+
+
+def _pack_steps(pack: Mapping[str, Any]) -> tuple[Mapping[str, Any], ...]:
+    return tuple(step for step in _sequence(pack.get("steps")) if isinstance(step, Mapping))
+
+
+def _chain_pack_steps(pack: Mapping[str, Any], tasks: Mapping[str, Any]) -> None:
+    for step in _pack_steps(pack):
+        step_name = str(step.get("name") or "")
+        if step_name not in tasks:
+            continue
+        for dependency in _sequence(step.get("depends_on")):
+            dependency_name = str(dependency)
+            if dependency_name in tasks:
+                _chain(tasks[dependency_name], tasks[step_name])
+
+
+def _terminal_hook_task_ids(pack: Mapping[str, Any]) -> tuple[str, ...]:
+    hook_steps = tuple(step for step in _pack_steps(pack) if step.get("phase") == "pre_hook")
+    dependencies = {str(dependency) for step in hook_steps for dependency in _sequence(step.get("depends_on"))}
+    return tuple(str(step["name"]) for step in hook_steps if str(step.get("name")) not in dependencies)
+
+
+def _deserialize_pod_spec(pod_spec: Mapping[str, Any]) -> object:
+    payload = dict(pod_spec)
+    try:
+        from kubernetes.client import ApiClient
+        from kubernetes.client import models as k8s
+    except Exception:
+        return payload
+    return ApiClient()._ApiClient__deserialize_model(payload, k8s.V1Pod)
+
+
+def _chain(upstream: Any, downstream: Any) -> None:
+    try:
+        upstream >> downstream
+    except TypeError:
+        return None
+
+
+__all__ = ["build_dpone_gitops_task_group_from_pack", "load_dpone_airflow_pack"]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/runtime_adapter.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+DEFAULT_ARTIFACT_DIR = ".dpone/gitops/airflow"
+KPO_KWARGS_FILE = "kpo-kwargs.json"
+POD_SPEC_FILE = "pod-spec.yaml"
+POD_CONTRACT_FILE = "pod-contract.json"
+
+_CONTRACT_OWNED_KPO_FIELDS = frozenset({"pod_template_file", "do_xcom_push", "cmds", "arguments"})
+
+
+class DponeAirflowArtifactError(RuntimeError):
+    """Base error for Airflow DAG-side dpone artifact loading."""
+
+
+class DponeAirflowContractError(DponeAirflowArtifactError):
+    """Raised when generated dpone Airflow artifacts are missing or unsafe."""
+
+    def __init__(self, message: str, *, blockers: tuple[dict[str, str], ...]) -> None:
+        super().__init__(message)
+        self.blockers = blockers
+
+
+def load_dpone_kpo_kwargs(
+    artifact_dir: str | Path = DEFAULT_ARTIFACT_DIR,
+    *,
+    task_id: str = "dpone_gitops_runtime",
+    name: str | None = None,
+    labels: Mapping[str, Any] | None = None,
+    annotations: Mapping[str, Any] | None = None,
+    operator_overrides: Mapping[str, Any] | None = None,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """Load generated KubernetesPodOperator kwargs and apply DAG-local fields.
+
+    The generated `kpo-kwargs.json` remains the canonical contract. This helper
+    only rewrites the local `pod_template_file`, keeps final XCom enabled, and
+    applies caller-owned DAG metadata such as task id, labels, annotations,
+    retries, pools, and queues.
+    """
+
+    root = Path(artifact_dir)
+    overrides = _operator_overrides(operator_overrides)
+    if validate:
+        validate_dpone_artifacts(root)
+    kwargs = _load_json_mapping(root / KPO_KWARGS_FILE, kind="kpo_kwargs")
+    kwargs["task_id"] = task_id
+    kwargs["name"] = name or task_id
+    kwargs["pod_template_file"] = str(root / POD_SPEC_FILE)
+    kwargs["do_xcom_push"] = True
+    kwargs["labels"] = _merge_mapping(kwargs.get("labels"), labels)
+    kwargs["annotations"] = _merge_mapping(kwargs.get("annotations"), annotations)
+    kwargs.update(overrides)
+    return kwargs
+
+
+def build_dpone_gitops_task_from_artifacts(
+    *,
+    dag: Any,
+    artifact_dir: str | Path = DEFAULT_ARTIFACT_DIR,
+    task_id: str = "dpone_gitops_runtime",
+    name: str | None = None,
+    labels: Mapping[str, Any] | None = None,
+    annotations: Mapping[str, Any] | None = None,
+    operator_overrides: Mapping[str, Any] | None = None,
+) -> Any:
+    """Build a KubernetesPodOperator from generated dpone artifacts."""
+
+    from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
+
+    kwargs = load_dpone_kpo_kwargs(
+        artifact_dir,
+        task_id=task_id,
+        name=name,
+        labels=labels,
+        annotations=annotations,
+        operator_overrides=operator_overrides,
+    )
+    return KubernetesPodOperator(dag=dag, **kwargs)
+
+
+def validate_dpone_artifacts(
+    artifact_dir: str | Path = DEFAULT_ARTIFACT_DIR,
+    *,
+    require_pod_contract: bool = True,
+) -> dict[str, Any]:
+    """Validate a generated dpone Airflow artifact directory.
+
+    This is intentionally a parse-time safety check for DAG repositories. It
+    does not parse manifests, discover sparse paths, mutate Kubernetes specs, or
+    make network calls.
+    """
+
+    root = Path(artifact_dir)
+    entries = _artifact_entries(root=root, require_pod_contract=require_pod_contract)
+    blockers = _missing_required_blockers(entries)
+    kpo_kwargs: Mapping[str, Any] = {}
+    pod_spec: Mapping[str, Any] = {}
+    pod_contract: Mapping[str, Any] = {}
+    if not blockers:
+        kpo_kwargs, pod_spec, pod_contract, parse_blockers = _load_artifacts(
+            root=root,
+            require_pod_contract=require_pod_contract,
+        )
+        blockers.extend(parse_blockers)
+    if not blockers:
+        blockers.extend(
+            _contract_blockers(
+                root=root,
+                kpo_kwargs=kpo_kwargs,
+                pod_spec=pod_spec,
+                pod_contract=pod_contract,
+                require_pod_contract=require_pod_contract,
+            )
+        )
+    report = {
+        "kind": "dpone.airflow_runtime_artifacts",
+        "artifact_dir": str(root),
+        "entries": entries,
+        "warnings": [],
+        "blockers": blockers,
+    }
+    if blockers:
+        message = "dpone Airflow artifact directory is not ready: " + "; ".join(
+            f"{item['code']} at {item['path']}" for item in blockers
+        )
+        raise DponeAirflowContractError(message, blockers=tuple(blockers))
+    return report
+
+
+def _load_artifacts(
+    *,
+    root: Path,
+    require_pod_contract: bool,
+) -> tuple[Mapping[str, Any], Mapping[str, Any], Mapping[str, Any], list[dict[str, str]]]:
+    blockers: list[dict[str, str]] = []
+    kpo_kwargs = _load_json_mapping_or_blocker(root / KPO_KWARGS_FILE, kind="kpo_kwargs", blockers=blockers)
+    pod_spec = _load_yaml_mapping_or_blocker(root / POD_SPEC_FILE, blockers=blockers)
+    pod_contract: Mapping[str, Any] = {}
+    if require_pod_contract:
+        pod_contract = _load_json_mapping_or_blocker(root / POD_CONTRACT_FILE, kind="pod_contract", blockers=blockers)
+    return kpo_kwargs, pod_spec, pod_contract, blockers
+
+
+def _load_json_mapping(path: Path, *, kind: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise DponeAirflowContractError(
+            f"Required dpone Airflow artifact is missing: {path}",
+            blockers=(_blocker(f"{kind}_missing", str(path), "Required artifact does not exist"),),
+        ) from exc
+    except json.JSONDecodeError as exc:
+        raise DponeAirflowContractError(
+            f"Required dpone Airflow artifact is not valid JSON: {path}",
+            blockers=(_blocker(f"{kind}_json_invalid", str(path), exc.msg),),
+        ) from exc
+    if not isinstance(payload, dict):
+        raise DponeAirflowContractError(
+            f"Required dpone Airflow artifact must be a JSON object: {path}",
+            blockers=(_blocker(f"{kind}_json_invalid", str(path), "JSON artifact must be an object"),),
+        )
+    return payload
+
+
+def _load_json_mapping_or_blocker(
+    path: Path,
+    *,
+    kind: str,
+    blockers: list[dict[str, str]],
+) -> Mapping[str, Any]:
+    try:
+        return _load_json_mapping(path, kind=kind)
+    except DponeAirflowContractError as exc:
+        blockers.extend(exc.blockers)
+    return {}
+
+
+def _load_yaml_mapping_or_blocker(path: Path, *, blockers: list[dict[str, str]]) -> Mapping[str, Any]:
+    try:
+        import yaml
+
+        payload = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        blockers.append(_blocker("pod_spec_missing", str(path), "Required pod spec artifact does not exist"))
+        return {}
+    except Exception as exc:  # noqa: BLE001 - parser differences should become contract blockers
+        blockers.append(_blocker("pod_spec_yaml_invalid", str(path), f"Pod spec YAML could not be parsed: {exc}"))
+        return {}
+    if not isinstance(payload, Mapping):
+        blockers.append(_blocker("pod_spec_yaml_invalid", str(path), "Pod spec YAML must be an object"))
+        return {}
+    return payload
+
+
+def _artifact_entries(*, root: Path, require_pod_contract: bool) -> list[dict[str, Any]]:
+    entries = [
+        _entry(root / KPO_KWARGS_FILE, kind="kpo_kwargs", required=True),
+        _entry(root / POD_SPEC_FILE, kind="pod_spec", required=True),
+    ]
+    entries.append(_entry(root / POD_CONTRACT_FILE, kind="pod_contract", required=require_pod_contract))
+    return entries
+
+
+def _entry(path: Path, *, kind: str, required: bool) -> dict[str, Any]:
+    return {
+        "path": str(path),
+        "kind": kind,
+        "required": required,
+        "exists": path.exists(),
+        "reason": "dpone Airflow runtime artifact",
+    }
+
+
+def _missing_required_blockers(entries: list[dict[str, Any]]) -> list[dict[str, str]]:
+    return [
+        _blocker(f"{entry['kind']}_missing", str(entry["path"]), "Required artifact does not exist")
+        for entry in entries
+        if entry["required"] and not entry["exists"]
+    ]
+
+
+def _contract_blockers(
+    *,
+    root: Path,
+    kpo_kwargs: Mapping[str, Any],
+    pod_spec: Mapping[str, Any],
+    pod_contract: Mapping[str, Any],
+    require_pod_contract: bool,
+) -> list[dict[str, str]]:
+    blockers: list[dict[str, str]] = []
+    _append_kpo_blockers(root=root, kpo_kwargs=kpo_kwargs, pod_contract=pod_contract, blockers=blockers)
+    _append_pod_spec_blockers(root=root, pod_spec=pod_spec, blockers=blockers)
+    if require_pod_contract:
+        _append_pod_contract_blockers(root=root, pod_contract=pod_contract, blockers=blockers)
+    return blockers
+
+
+def _append_kpo_blockers(
+    *,
+    root: Path,
+    kpo_kwargs: Mapping[str, Any],
+    pod_contract: Mapping[str, Any],
+    blockers: list[dict[str, str]],
+) -> None:
+    path = str(root / KPO_KWARGS_FILE)
+    if kpo_kwargs.get("do_xcom_push") is not True:
+        blockers.append(_blocker("kpo_xcom_push_required", path, "kpo-kwargs.json must set do_xcom_push=true"))
+    if not kpo_kwargs.get("cmds"):
+        blockers.append(_blocker("kpo_cmds_required", path, "kpo-kwargs.json must include runtime cmds"))
+    if not kpo_kwargs.get("arguments"):
+        blockers.append(_blocker("kpo_arguments_required", path, "kpo-kwargs.json must include runtime arguments"))
+    pod_template = str(kpo_kwargs.get("pod_template_file") or "").strip()
+    expected = str(pod_contract.get("pod_spec_path") or "").strip()
+    if expected and pod_template != expected:
+        blockers.append(
+            _blocker("kpo_pod_template_mismatch", path, "kpo-kwargs.json pod_template_file must match pod-contract")
+        )
+    if not expected and not pod_template.endswith(POD_SPEC_FILE):
+        blockers.append(_blocker("kpo_pod_template_required", path, "kpo-kwargs.json must reference pod-spec.yaml"))
+
+
+def _append_pod_spec_blockers(
+    *,
+    root: Path,
+    pod_spec: Mapping[str, Any],
+    blockers: list[dict[str, str]],
+) -> None:
+    path = str(root / POD_SPEC_FILE)
+    if pod_spec.get("kind") != "Pod":
+        blockers.append(_blocker("pod_spec_kind_invalid", path, "pod-spec.yaml kind must be Pod"))
+    containers = _mapping(pod_spec.get("spec")).get("containers")
+    first_container = containers[0] if isinstance(containers, list) and containers else {}
+    if _mapping(first_container).get("name") != "base":
+        blockers.append(_blocker("pod_spec_base_container_missing", path, "pod-spec.yaml first container must be base"))
+
+
+def _append_pod_contract_blockers(
+    *,
+    root: Path,
+    pod_contract: Mapping[str, Any],
+    blockers: list[dict[str, str]],
+) -> None:
+    path = str(root / POD_CONTRACT_FILE)
+    if pod_contract.get("kind") != "gitops.airflow_pod_contract":
+        blockers.append(
+            _blocker("pod_contract_kind_invalid", path, "pod-contract.json kind must be gitops.airflow_pod_contract")
+        )
+    xcom = _mapping(pod_contract.get("xcom"))
+    if xcom.get("return_path") != "/airflow/xcom/return.json" or xcom.get("enabled") is not True:
+        blockers.append(_blocker("pod_contract_xcom_invalid", path, "pod contract must enable final XCom return.json"))
+
+
+def _operator_overrides(overrides: Mapping[str, Any] | None) -> dict[str, Any]:
+    resolved = dict(overrides or {})
+    forbidden = sorted(_CONTRACT_OWNED_KPO_FIELDS.intersection(resolved))
+    if forbidden:
+        fields = ", ".join(forbidden)
+        raise ValueError(f"operator_overrides cannot replace dpone contract-owned KPO fields: {fields}")
+    return resolved
+
+
+def _merge_mapping(base: object, extra: Mapping[str, Any] | None) -> dict[str, Any]:
+    merged = dict(base) if isinstance(base, Mapping) else {}
+    merged.update(dict(extra or {}))
+    return merged
+
+
+def _mapping(value: object) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _blocker(code: str, path: str, message: str) -> dict[str, str]:
+    return {"code": code, "path": path, "message": message, "source": "dpone.airflow.runtime_adapter"}
+
+
+__all__ = [
+    "DEFAULT_ARTIFACT_DIR",
+    "DponeAirflowArtifactError",
+    "DponeAirflowContractError",
+    "build_dpone_gitops_task_from_artifacts",
+    "load_dpone_kpo_kwargs",
+    "validate_dpone_artifacts",
+]

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/step_tasks.py

@@ -0,0 +1,95 @@
+"""Build visible Airflow KPO tasks from dpone GitOps run-spec steps."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from dpone_airflow_pack.runtime_adapter import DEFAULT_ARTIFACT_DIR, load_dpone_kpo_kwargs
+
+RUN_SPEC_FILE = "run-spec.json"
+
+
+def build_dpone_gitops_step_tasks_from_artifacts(
+    *,
+    dag: Any,
+    artifact_dir: str | Path = DEFAULT_ARTIFACT_DIR,
+    labels: Mapping[str, Any] | None = None,
+    annotations: Mapping[str, Any] | None = None,
+    operator_overrides: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build one visible KubernetesPodOperator per run-spec step."""
+
+    from airflow.providers.cncf.kubernetes.operators.pod import KubernetesPodOperator
+
+    root = Path(artifact_dir)
+    steps = _load_run_spec_steps(root)
+    tasks: dict[str, Any] = {}
+    for step in steps:
+        name = str(step.get("name") or "").strip()
+        command = str(step.get("command") or "").strip()
+        if not name or not command:
+            continue
+        kwargs = _load_step_kpo_kwargs(
+            root,
+            step_name=name,
+            command=command,
+            do_xcom_push=str(step.get("kind") or "") == "dpone_run",
+            labels=labels,
+            annotations=annotations,
+            operator_overrides=operator_overrides,
+        )
+        tasks[name] = KubernetesPodOperator(dag=dag, **kwargs)
+    _wire_step_dependencies(tasks=tasks, steps=steps)
+    return tasks
+
+
+def _load_run_spec_steps(root: Path) -> list[Mapping[str, Any]]:
+    payload = json.loads((root / RUN_SPEC_FILE).read_text(encoding="utf-8"))
+    steps = payload.get("steps")
+    return [step for step in steps if isinstance(step, Mapping)] if isinstance(steps, list) else []
+
+
+def _load_step_kpo_kwargs(
+    root: Path,
+    *,
+    step_name: str,
+    command: str,
+    do_xcom_push: bool,
+    labels: Mapping[str, Any] | None,
+    annotations: Mapping[str, Any] | None,
+    operator_overrides: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    kwargs = load_dpone_kpo_kwargs(
+        root,
+        task_id=step_name,
+        name=step_name,
+        labels=labels,
+        annotations=annotations,
+        operator_overrides=operator_overrides,
+    )
+    kwargs["cmds"] = ["/bin/sh", "-ec"]
+    kwargs["arguments"] = [command]
+    kwargs["do_xcom_push"] = do_xcom_push
+    return kwargs
+
+
+def _wire_step_dependencies(*, tasks: Mapping[str, Any], steps: list[Mapping[str, Any]]) -> None:
+    for step in steps:
+        task = tasks.get(str(step.get("name") or ""))
+        dependencies = step.get("depends_on")
+        if task is None or not isinstance(dependencies, list):
+            continue
+        for dependency in dependencies:
+            upstream = tasks.get(str(dependency))
+            if upstream is not None:
+                _chain(upstream, task)
+
+
+def _chain(upstream: Any, downstream: Any) -> None:
+    try:
+        upstream >> downstream
+    except TypeError:
+        return None

dpone_airflow_pack-0.44.0/src/dpone_airflow_pack/xcom_sidecar.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_XCOM_SIDECAR_IMAGE = "alpine:3.23.4"
+XCOM_SIDECAR_CONTAINER_NAME = "airflow-xcom-sidecar"
+
+
+@dataclass(frozen=True)
+class XComSidecarRuntimeConfig:
+    image: str = DEFAULT_XCOM_SIDECAR_IMAGE
+
+
+def pin_xcom_sidecar_image(pod: Any, image: str = DEFAULT_XCOM_SIDECAR_IMAGE) -> Any:
+    containers = getattr(getattr(pod, "spec", None), "containers", None) or []
+    for container in containers:
+        if getattr(container, "name", None) == XCOM_SIDECAR_CONTAINER_NAME:
+            container.image = image
+            break
+    return pod
+
+
+__all__ = [
+    "DEFAULT_XCOM_SIDECAR_IMAGE",
+    "XCOM_SIDECAR_CONTAINER_NAME",
+    "XComSidecarRuntimeConfig",
+    "pin_xcom_sidecar_image",
+]