contractforge-databricks 0.1.0__py3-none-any.whl

contractforge_databricks/capabilities/runtime.py

@@ -0,0 +1,111 @@
+"""Runtime classification helpers for Databricks capability evaluation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contractforge_databricks.capabilities.models import CapabilityEvidence, RuntimeKind
+
+SERVERLESS_TRUE_KEYS = (
+    "spark.databricks.serverless.enabled",
+    "spark.databricks.compute.serverless.enabled",
+)
+DATABRICKS_ENVIRONMENT_KEYS = (
+    "DB_INSTANCE_TYPE",
+    "DATABRICKS_RUNTIME_VERSION",
+    "DATABRICKS_ENV_VERSION",
+    "SPARK_CONNECT_MODE_ENABLED",
+    "SPARK_EXECUTOR_ATTRIBUTE_POD_NAME",
+)
+CLASSIC_CLUSTER_KEYS = (
+    "spark.databricks.clusterUsageTags.clusterId",
+    "spark.databricks.clusterUsageTags.clusterName",
+    "spark.databricks.clusterUsageTags.clusterType",
+)
+JOB_METADATA_KEY_FRAGMENTS = ("job", "run")
+
+
+def runtime_kind(
+    *,
+    runtime_type: str | None,
+    spark_conf: dict[str, str],
+    environment: dict[str, str] | None = None,
+) -> RuntimeKind:
+    normalized = (runtime_type or "").strip().lower()
+    if normalized in {"serverless", "serverless_job", "databricks_serverless"}:
+        return "databricks_serverless"
+    if normalized == "classic":
+        return "databricks_classic" if has_databricks_conf(spark_conf) else "spark"
+    if normalized in {"classic_cluster", "classic_existing_cluster", "databricks_classic"}:
+        return "databricks_classic"
+    if is_serverless_runtime(spark_conf, environment=environment):
+        return "databricks_serverless"
+    if has_databricks_conf(spark_conf):
+        return "databricks_classic"
+    return "unknown" if not spark_conf else "spark"
+
+
+def runtime_evidence(
+    *,
+    runtime_kind: RuntimeKind,
+    spark_version: str | None,
+    spark_conf: dict[str, str],
+    environment: dict[str, str] | None = None,
+) -> tuple[CapabilityEvidence, ...]:
+    evidence = [_e("runtime_kind", "Runtime classified from provided evidence.", runtime_kind)]
+    if spark_version:
+        evidence.append(_e("spark_version", "Spark version was provided.", spark_version))
+    for key in sorted(spark_conf):
+        if key.startswith("spark.databricks."):
+            evidence.append(_e("spark_conf", "Databricks Spark configuration key detected.", key))
+    for key in sorted(environment or {}):
+        if key in DATABRICKS_ENVIRONMENT_KEYS:
+            evidence.append(_e("environment", "Databricks runtime environment key detected.", key))
+    return tuple(evidence)
+
+
+def has_databricks_conf(spark_conf: dict[str, str]) -> bool:
+    return any(key.startswith("spark.databricks.") and str(value).strip() for key, value in spark_conf.items())
+
+
+def is_serverless_runtime(
+    spark_conf: dict[str, str],
+    *,
+    environment: dict[str, str] | None = None,
+) -> bool:
+    return is_serverless_conf(spark_conf) or is_serverless_environment(environment or {})
+
+
+def is_serverless_conf(spark_conf: dict[str, str]) -> bool:
+    normalized = {str(key): str(value) for key, value in spark_conf.items()}
+    if any(normalized.get(key, "").strip().lower() == "true" for key in SERVERLESS_TRUE_KEYS):
+        return True
+    if any(key.startswith("spark.databricks.") and "serverless" in value.lower() for key, value in normalized.items()):
+        return True
+    return _looks_like_databricks_serverless_job(normalized)
+
+
+def is_serverless_environment(environment: dict[str, str]) -> bool:
+    normalized = {str(key): str(value) for key, value in environment.items()}
+    return any(key in DATABRICKS_ENVIRONMENT_KEYS and "serverless" in value.lower() for key, value in normalized.items())
+
+
+def is_three_part_name(target_table: str | None) -> bool:
+    return bool(target_table and len([part for part in target_table.split(".") if part.strip()]) >= 3)
+
+
+def _looks_like_databricks_serverless_job(spark_conf: dict[str, str]) -> bool:
+    if not has_databricks_conf(spark_conf):
+        return False
+    if any(spark_conf.get(key, "").strip() for key in CLASSIC_CLUSTER_KEYS):
+        return False
+    return any(
+        key.startswith("spark.databricks.")
+        and all(fragment in key.lower() for fragment in JOB_METADATA_KEY_FRAGMENTS)
+        and str(value).strip()
+        for key, value in spark_conf.items()
+    )
+
+
+def _e(source: str, message: str, value: Any = None) -> CapabilityEvidence:
+    return CapabilityEvidence(source=source, message=message, value=None if value is None else str(value))

contractforge_databricks/capabilities/uc.py

@@ -0,0 +1,47 @@
+"""Unity Catalog capability issue helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from contractforge_databricks.capabilities.evaluate import evaluate_databricks_capabilities
+from contractforge_databricks.capabilities.models import DatabricksCapabilities
+
+UC_CAPABILITY_ALIASES = {
+    "table_comments": "uc_table_comments",
+    "column_comments": "uc_column_comments",
+    "table_tags": "uc_table_tags",
+    "column_tags": "uc_column_tags",
+    "grants": "uc_grants",
+    "row_filters": "uc_row_filters",
+    "column_masks": "uc_column_masks",
+}
+
+
+def uc_capability_issues(
+    target_table: str,
+    requirements: Iterable[tuple[str, str, str, str]],
+    *,
+    capabilities: DatabricksCapabilities | None = None,
+    runtime_type: str | None = "serverless",
+) -> list[dict[str, Any]]:
+    caps = capabilities or evaluate_databricks_capabilities(target_table=target_table, runtime_type=runtime_type)
+    issues = []
+    for capability, scope, obj, severity in requirements:
+        native_name = UC_CAPABILITY_ALIASES.get(capability, capability)
+        if caps.supports(native_name):
+            continue
+        issues.append(
+            {
+                "severity": severity,
+                "scope": scope,
+                "object": obj,
+                "capability": native_name,
+                "status": caps.status(native_name),
+                "message": (
+                    f"{native_name} is not supported for {target_table}. "
+                    "Use a three-part Unity Catalog table or remove the feature from the contract."
+                ),
+            }
+        )
+    return issues

contractforge_databricks/cli.py

@@ -0,0 +1,196 @@
+"""CLI entrypoint for Databricks adapter utilities."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from contractforge_databricks.api import render_databricks_contract
+from contractforge_databricks.cli_deploy import add_deploy_parser, deploy_command
+from contractforge_databricks.cli_governance import add_governance_parser, governance_command
+from contractforge_databricks.cli_io import load_contract_input, load_mapping, write_artifacts, write_mapping
+from contractforge_databricks.cli_maintenance import add_maintenance_parser, maintenance_command
+from contractforge_databricks.dashboards import render_control_dashboard_artifacts
+from contractforge_databricks.presets import list_presets, preset_details
+from contractforge_databricks.templates import (
+    contract_template_details,
+    contract_template_files,
+    get_contract_template,
+    list_contract_templates,
+    recommend_contract_templates,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="contractforge-databricks")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    presets = sub.add_parser("presets", help="List or inspect Databricks adapter presets")
+    presets_sub = presets.add_subparsers(dest="preset_command", required=True)
+    presets_list = presets_sub.add_parser("list")
+    presets_list.add_argument("--indent", type=int, default=2)
+    presets_show = presets_sub.add_parser("show")
+    presets_show.add_argument("names", nargs="+")
+    presets_show.add_argument("--indent", type=int, default=2)
+
+    templates = sub.add_parser("templates", help="List, show, recommend or write Databricks contract templates")
+    templates_sub = templates.add_subparsers(dest="template_command", required=True)
+    templates_list = templates_sub.add_parser("list")
+    templates_list.add_argument("--indent", type=int, default=2)
+    templates_show = templates_sub.add_parser("show")
+    templates_show.add_argument("name")
+    templates_show.add_argument("--metadata-only", action="store_true")
+    templates_show.add_argument("--indent", type=int, default=2)
+    templates_write = templates_sub.add_parser("write")
+    templates_write.add_argument("name")
+    templates_write.add_argument("--output", required=True, type=Path)
+    templates_write.add_argument("--force", action="store_true")
+    templates_write.add_argument("--indent", type=int, default=2)
+    templates_wizard = templates_sub.add_parser("wizard")
+    templates_wizard.add_argument("--layer")
+    templates_wizard.add_argument("--source")
+    templates_wizard.add_argument("--mode")
+    templates_wizard.add_argument("--pattern")
+    templates_wizard.add_argument("--limit", type=int, default=5)
+    templates_wizard.add_argument("--name")
+    templates_wizard.add_argument("--output", type=Path)
+    templates_wizard.add_argument("--force", action="store_true")
+    templates_wizard.add_argument("--indent", type=int, default=2)
+
+    render = sub.add_parser("render", help="Render Databricks review artifacts for a contract JSON/YAML file")
+    render.add_argument("contract", type=Path)
+    render.add_argument("--environment", type=Path)
+    render.add_argument("--output-dir", type=Path)
+    render.add_argument("--indent", type=int, default=2)
+
+    dashboard = sub.add_parser("dashboard", help="Render Databricks control-table dashboard artifacts")
+    dashboard.add_argument("--catalog", default="main")
+    dashboard.add_argument("--schema", default="ops")
+    dashboard.add_argument("--lookback-days", type=int, default=7)
+    dashboard.add_argument("--output-dir", type=Path)
+    dashboard.add_argument("--indent", type=int, default=2)
+
+    add_governance_parser(sub)
+    add_maintenance_parser(sub)
+    add_deploy_parser(sub)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return _dispatch(args)
+    except Exception as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    if args.command == "presets":
+        return _presets(args)
+    if args.command == "templates":
+        return _templates(args)
+    if args.command == "render":
+        return _render_contract(args)
+    if args.command == "dashboard":
+        return _dashboard(args)
+    governance_result = governance_command(args)
+    if governance_result is not None:
+        return governance_result
+    if args.command == "maintenance":
+        return maintenance_command(args)
+    deploy_result = deploy_command(args)
+    if deploy_result is not None:
+        return deploy_result
+    raise ValueError(f"unsupported command: {args.command}")
+
+
+def _presets(args: argparse.Namespace) -> int:
+    if args.preset_command == "list":
+        return _print([preset_details(name) for name in list_presets()], args.indent)
+    if args.preset_command == "show":
+        return _print([preset_details(name) for name in args.names], args.indent)
+    raise ValueError(f"unsupported presets command: {args.preset_command}")
+
+
+def _templates(args: argparse.Namespace) -> int:
+    if args.template_command == "list":
+        return _print([contract_template_details(name) for name in list_contract_templates()], args.indent)
+    if args.template_command == "show":
+        payload = contract_template_details(args.name) if args.metadata_only else get_contract_template(args.name)
+        return _print(payload, args.indent)
+    if args.template_command == "write":
+        written = _write_template_files(args.name, args.output, force=args.force)
+        return _print({"status": "SUCCESS", "template": args.name, "written": written}, args.indent)
+    if args.template_command == "wizard":
+        recommendations = recommend_contract_templates(
+            layer=args.layer,
+            source=args.source,
+            mode=args.mode,
+            pattern=args.pattern,
+            limit=args.limit,
+        )
+        result: dict[str, Any] = {
+            "status": "SUCCESS",
+            "criteria": {
+                "layer": args.layer,
+                "source": args.source,
+                "mode": args.mode,
+                "pattern": args.pattern,
+            },
+            "recommendations": recommendations,
+        }
+        if args.output:
+            if not recommendations:
+                raise ValueError("no compatible template found for the provided criteria")
+            selected = args.name or str(recommendations[0]["name"])
+            result["selected_template"] = selected
+            result["written"] = _write_template_files(selected, args.output, force=args.force)
+        return _print(result, args.indent)
+    raise ValueError(f"unsupported templates command: {args.template_command}")
+
+
+def _render_contract(args: argparse.Namespace) -> int:
+    contract, bundle_environment = load_contract_input(args.contract)
+    environment = load_mapping(args.environment) if args.environment else bundle_environment
+    artifacts = render_databricks_contract(contract, environment=environment).artifacts
+    if args.output_dir:
+        written = write_artifacts(args.output_dir, artifacts)
+        return _print({"status": "SUCCESS", "written": written}, args.indent)
+    return _print(artifacts, args.indent)
+
+
+def _dashboard(args: argparse.Namespace) -> int:
+    artifacts = render_control_dashboard_artifacts(
+        catalog=args.catalog,
+        schema=args.schema,
+        lookback_days=args.lookback_days,
+    )
+    if args.output_dir:
+        written = write_artifacts(args.output_dir, artifacts)
+        return _print({"status": "SUCCESS", "written": written}, args.indent)
+    return _print(artifacts, args.indent)
+
+
+def _write_template_files(name: str, output: Path, *, force: bool) -> list[str]:
+    files = contract_template_files(name)
+    written = []
+    for kind, payload in files.items():
+        path = output.with_suffix(f".{kind}.yaml")
+        write_mapping(path, payload, force=force)
+        written.append(str(path))
+    return written
+
+
+def _print(payload: object, indent: int) -> int:
+    print(json.dumps(payload, indent=indent, sort_keys=True, default=str))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

contractforge_databricks/cli_deploy.py

@@ -0,0 +1,98 @@
+"""Databricks deployment CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Callable
+
+from contractforge_databricks.runtime.deploy import (
+    deploy_databricks_bundle,
+    deploy_databricks_project,
+    render_databricks_project_bundle_file,
+)
+
+
+def add_deploy_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    project = subparsers.add_parser("deploy-project", help="Validate/deploy/run a project Databricks Asset Bundle.")
+    project.add_argument("project", type=Path)
+    project.add_argument("--render-bundle", action="store_true", help="Render databricks.yml from project.yaml before deployment.")
+    project.add_argument("--force-render", action="store_true", help="Overwrite the rendered bundle when --render-bundle is used.")
+    _add_common_deploy_args(project)
+
+    bundle = subparsers.add_parser("deploy-bundle", help="Validate/deploy/run a Databricks Asset Bundle directory.")
+    bundle.add_argument("bundle", type=Path)
+    _add_common_deploy_args(bundle)
+
+    render = subparsers.add_parser("render-project-bundle", help="Render databricks.yml from project.yaml scheduling metadata.")
+    render.add_argument("project", type=Path)
+    render.add_argument("--output", type=Path, default=Path("databricks.yml"))
+    render.add_argument("--target", default="dev")
+    render.add_argument("--force", action="store_true")
+    render.add_argument("--indent", type=int, default=2)
+
+
+def deploy_command(args: argparse.Namespace) -> int | None:
+    handler = _COMMANDS.get(args.command)
+    return None if handler is None else handler(args)
+
+
+def _handle_project(args: argparse.Namespace) -> int:
+    return _print(
+        deploy_databricks_project(
+            args.project,
+            profile=args.profile,
+            target=args.target,
+            run=args.run,
+            validate=not args.skip_validate,
+            render_bundle=args.render_bundle,
+            force_render=args.force_render,
+        ),
+        args.indent,
+    )
+
+
+def _handle_bundle(args: argparse.Namespace) -> int:
+    return _print(
+        deploy_databricks_bundle(
+            args.bundle,
+            profile=args.profile,
+            target=args.target,
+            run=args.run,
+            validate=not args.skip_validate,
+        ),
+        args.indent,
+    )
+
+
+def _handle_render_project_bundle(args: argparse.Namespace) -> int:
+    return _print(
+        render_databricks_project_bundle_file(
+            args.project,
+            args.output,
+            target=args.target,
+            force=args.force,
+        ),
+        args.indent,
+    )
+
+
+def _add_common_deploy_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--profile")
+    parser.add_argument("--target")
+    parser.add_argument("--run", action="store_true", help="Run the deployed bundle job after deployment.")
+    parser.add_argument("--skip-validate", action="store_true")
+    parser.add_argument("--indent", type=int, default=2)
+
+
+def _print(payload: object, indent: int) -> int:
+    print(json.dumps(payload, indent=indent, sort_keys=True, default=str))
+    return 0
+
+
+_COMMANDS: dict[str, Callable[[argparse.Namespace], int]] = {
+    "deploy-project": _handle_project,
+    "deploy-bundle": _handle_bundle,
+    "render-project-bundle": _handle_render_project_bundle,
+}

contractforge_databricks/cli_governance.py

@@ -0,0 +1,142 @@
+"""Databricks governance review commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from contractforge_core.cli_io import yaml_load
+from contractforge_core.contracts import compose_contract_sections, semantic_contract_from_mapping
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.annotations import render_annotations_sql
+from contractforge_databricks.environment import DatabricksEnvironment
+from contractforge_databricks.governance import render_access_sql, render_governance_sql
+from contractforge_databricks.operations import render_operations_insert_sql, render_operations_json
+
+
+def add_governance_parser(subparsers: Any) -> None:
+    preview = subparsers.add_parser("governance-preview", help="Render Databricks governance review artifacts")
+    preview.add_argument("paths", nargs="+", type=Path)
+    preview.add_argument("--output-dir", type=Path)
+    preview.add_argument("--indent", type=int, default=2)
+
+    apply_plan = subparsers.add_parser("governance-apply-plan", help="Render Databricks SQL that a runtime executor can apply")
+    apply_plan.add_argument("paths", nargs="+", type=Path)
+    apply_plan.add_argument("--output-dir", type=Path)
+    apply_plan.add_argument("--indent", type=int, default=2)
+
+
+def governance_command(args: Any) -> int | None:
+    if args.command == "governance-preview":
+        return _governance_preview(args)
+    if args.command == "governance-apply-plan":
+        return _governance_apply_plan(args)
+    return None
+
+
+def _governance_preview(args: Any) -> int:
+    artifacts = {}
+    for path in args.paths:
+        contract, environment = _load_contract(path)
+        prefix = _artifact_prefix(path)
+        env = DatabricksEnvironment.from_contract(environment)
+        artifacts[f"{prefix}.governance.sql"] = render_governance_sql(contract)
+        artifacts[f"{prefix}.annotations.sql"] = render_annotations_sql(contract)
+        artifacts[f"{prefix}.access.sql"] = render_access_sql(contract)
+        artifacts[f"{prefix}.operations.json"] = render_operations_json(contract)
+        artifacts[f"{prefix}.operations_evidence.sql"] = render_operations_insert_sql(
+            contract,
+            catalog=env.evidence_catalog,
+            schema=env.evidence_schema,
+        )
+    return _emit(artifacts, args.output_dir, args.indent)
+
+
+def _governance_apply_plan(args: Any) -> int:
+    artifacts = {}
+    for path in args.paths:
+        contract, environment = _load_contract(path)
+        prefix = _artifact_prefix(path)
+        env = DatabricksEnvironment.from_contract(environment)
+        sections = [
+            "-- ContractForge Databricks governance apply plan",
+            "-- Execute with a Databricks SQL/Spark runner owned by the adapter runtime.",
+            "",
+            render_governance_sql(contract),
+            render_operations_insert_sql(contract, catalog=env.evidence_catalog, schema=env.evidence_schema) + ";",
+        ]
+        artifacts[f"{prefix}.governance_apply_plan.sql"] = "\n".join(sections)
+    return _emit(artifacts, args.output_dir, args.indent)
+
+
+def _load_contract(path: Path) -> tuple[SemanticContract, dict[str, Any] | None]:
+    if _is_split_ingestion(path):
+        bundle = _load_bundle(path)
+        return bundle.semantic, bundle.environment
+    payload = _load_mapping(path)
+    environment = payload.get("environment") if isinstance(payload.get("environment"), dict) else None
+    return semantic_contract_from_mapping(payload), environment
+
+
+def _load_bundle(path: Path):
+    base = _bundle_base(path)
+    paths = {
+        "ingestion": base.with_suffix(".ingestion.yaml"),
+        "annotations": base.with_suffix(".annotations.yaml"),
+        "operations": base.with_suffix(".operations.yaml"),
+        "access": base.with_suffix(".access.yaml"),
+        "environment": base.with_suffix(".environment.yaml"),
+    }
+    ingestion = _load_mapping(paths["ingestion"])
+    optional = {name: _load_mapping(item) for name, item in paths.items() if name != "ingestion" and item.exists()}
+    return compose_contract_sections(
+        ingestion=ingestion,
+        annotations=optional.get("annotations"),
+        operations=optional.get("operations"),
+        access=optional.get("access"),
+        environment=optional.get("environment"),
+    )
+
+
+def _emit(artifacts: dict[str, str], output_dir: Path | None, indent: int) -> int:
+    if output_dir:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        written = []
+        for name, body in artifacts.items():
+            path = output_dir / name
+            path.write_text(body, encoding="utf-8")
+            written.append(str(path))
+        return _print({"status": "SUCCESS", "written": written}, indent)
+    return _print(artifacts, indent)
+
+
+def _load_mapping(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    payload = json.loads(text) if path.suffix.lower() == ".json" else yaml_load(text)
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain an object")
+    return payload
+
+
+def _artifact_prefix(path: Path) -> str:
+    name = _bundle_base(path).name
+    return name.replace(".", "_")
+
+
+def _bundle_base(path: Path) -> Path:
+    if _is_split_ingestion(path):
+        name = path.name
+        for suffix in (".ingestion.yaml", ".ingestion.yml", ".ingestion.json"):
+            if name.endswith(suffix):
+                return path.with_name(name[: -len(suffix)])
+    return path
+
+
+def _is_split_ingestion(path: Path) -> bool:
+    return path.is_file() and ".ingestion." in path.name
+
+
+def _print(payload: object, indent: int) -> int:
+    print(json.dumps(payload, indent=indent, sort_keys=True, default=str))
+    return 0

contractforge_databricks/cli_io.py

@@ -0,0 +1,91 @@
+"""Databricks CLI file IO helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from contractforge_core.contracts import load_contract_bundle
+
+
+def load_mapping(path: Path | None) -> dict[str, Any]:
+    if path is None:
+        return {}
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() == ".json":
+        payload = json.loads(text)
+    else:
+        payload = yaml_load(text)
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain an object")
+    return payload
+
+
+def load_contract_input(path: Path) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    if looks_like_split_contract(path):
+        bundle = load_contract_bundle(bundle_base(path))
+        environment = bundle.environment if isinstance(bundle.environment, dict) else None
+        return bundle.contract, environment
+    return load_mapping(path), None
+
+
+def write_mapping(path: Path, payload: dict[str, Any], *, force: bool) -> None:
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists; use --force to overwrite it")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(yaml_dump(payload), encoding="utf-8")
+
+
+def write_artifacts(output_dir: Path, artifacts: dict[str, str]) -> list[str]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    written = []
+    for name, body in artifacts.items():
+        path = output_dir / name
+        path.write_text(body, encoding="utf-8")
+        written.append(str(path))
+    return written
+
+
+def yaml_load(text: str) -> Any:
+    try:
+        import yaml  # type: ignore
+    except Exception as exc:  # pragma: no cover
+        raise RuntimeError("YAML support requires PyYAML; use JSON files or install PyYAML") from exc
+    return yaml.safe_load(text)
+
+
+def yaml_dump(payload: dict[str, Any]) -> str:
+    try:
+        import yaml  # type: ignore
+    except Exception:  # pragma: no cover
+        return json.dumps(payload, indent=2, sort_keys=False) + "\n"
+    return yaml.safe_dump(payload, allow_unicode=True, sort_keys=False)
+
+
+def looks_like_split_contract(path: Path) -> bool:
+    return any(marker in path.name for marker in (".ingestion.", ".annotations.", ".operations.", ".access.", ".environment."))
+
+
+def bundle_base(path: Path) -> Path:
+    name = path.name
+    for suffix in (
+        ".ingestion.yaml",
+        ".ingestion.yml",
+        ".ingestion.json",
+        ".annotations.yaml",
+        ".annotations.yml",
+        ".annotations.json",
+        ".operations.yaml",
+        ".operations.yml",
+        ".operations.json",
+        ".access.yaml",
+        ".access.yml",
+        ".access.json",
+        ".environment.yaml",
+        ".environment.yml",
+        ".environment.json",
+    ):
+        if name.endswith(suffix):
+            return path.with_name(name[: -len(suffix)])
+    return path