fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/source_azure.py

@@ -0,0 +1,586 @@
+"""Supervise connected source Foundation with exact human checkpoint approvals."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+from fdai_service_contracts.product_profile import ProductAddOn
+
+from fdai_deployment_cli.aks_preflight import current_target_binding, inspect_aks_target
+from fdai_deployment_cli.bootstrap_approval import selected_source
+from fdai_deployment_cli.catalog_review_profile import CatalogReviewDeploymentProfile
+from fdai_deployment_cli.contracts import load_json_object
+from fdai_deployment_cli.deployment_cost import inspect_aks_compute_cost
+from fdai_deployment_cli.deployment_deadline import DeploymentDeadline
+from fdai_deployment_cli.deployment_progress import (
+    begin_stage,
+    installer_activity,
+    progress_detail,
+)
+from fdai_deployment_cli.development_authority_profile import (
+    DevelopmentAuthorityDeploymentProfile,
+)
+from fdai_deployment_cli.hub_image_trust import HubImageSelection, load_selection
+from fdai_deployment_cli.installation_scope import (
+    InstallationOptions,
+    confirm_installation_scope,
+    started_installation_matches,
+)
+from fdai_deployment_cli.notification_recipients_input import (
+    NotificationRecipientsDeploymentInput,
+)
+from fdai_deployment_cli.operational_evidence_verifier_input import (
+    OperationalEvidenceVerifierDeploymentInput,
+)
+from fdai_deployment_cli.private_output import read_private_bytes
+from fdai_deployment_cli.runtime_profile import RuntimeDeploymentProfile
+from fdai_deployment_cli.source_deploy import prepare_source_deployment
+from fdai_deployment_cli.source_foundation import _copy_terraform
+from fdai_deployment_cli.source_input import inspect_source
+from fdai_deployment_cli.source_terraform import download_pinned_terraform
+from fdai_deployment_cli.standalone_application_completion import complete_application
+from fdai_deployment_cli.standalone_deploy import (
+    _current_operator_object_id as current_operator_object_id,
+)
+from fdai_deployment_cli.standalone_status import current_status, prior_attempt
+
+
+def plan_source_installation(
+    *,
+    source_root: Path,
+    work_dir: Path,
+    runtime_profile: RuntimeDeploymentProfile,
+    region: str,
+    monthly_cost_ceiling: int,
+    timeout_seconds: int,
+    foundation_workload: str = "fdai",
+    interactive: bool = False,
+    approval_file: Path | None = None,
+    installation_options: InstallationOptions | None = None,
+    confirm_initial: bool = False,
+    foundation_recovery_directory: Path | None = None,
+    operational_evidence_verifier_input: OperationalEvidenceVerifierDeploymentInput | None = None,
+    notification_recipients: NotificationRecipientsDeploymentInput | None = None,
+    development_authority_profile: DevelopmentAuthorityDeploymentProfile | None = None,
+    clear_development_authority_profile: bool = False,
+    hub_selection: HubImageSelection | None = None,
+) -> dict[str, object]:
+    """Advance source Foundation through exact human approvals, or stop for review.
+
+    No kit construction, signature fallback or licence activation occurs here.
+    Noninteractive use passes only an explicitly supplied approval to the shared
+    verifier and never prompts or adopts an ambient approval. Foundation handoff
+    alone keeps deployment_ready=false until application acceptance is connected.
+    """
+    if interactive and approval_file is not None:
+        raise ValueError("explicit source approval cannot be combined with interactive approval")
+    if hub_selection is None and (work_dir / "hub-images").exists():
+        raise ValueError("source builds cannot resume a Hub-image deployment")
+    hub_target_binding = None
+    if hub_selection is not None:
+        from fdai_deployment_cli.aks_preflight import _active_human_target
+        from fdai_deployment_cli.hub_image_deploy import record_deployment_request
+        from fdai_deployment_cli.target import compute_target_binding
+
+        hub_selection = load_selection(hub_selection.path, hub_selection.digest)
+        inspect_source(source_root, expected_commit=hub_selection.source_commit)
+        subscription_id, tenant_id = _active_human_target(
+            DeploymentDeadline(min(timeout_seconds, 60))
+        )
+        hub_target_binding = compute_target_binding(
+            subscription_id=subscription_id, tenant_id=tenant_id
+        )
+        record_deployment_request(hub_selection, subscription_id=subscription_id, region=region)
+    if foundation_recovery_directory is not None:
+        if hub_selection is not None:
+            from fdai_deployment_cli.hub_image_deploy import require_retained_hub_recovery
+
+            assert hub_target_binding is not None
+            require_retained_hub_recovery(
+                hub_selection, work_dir=work_dir, target_binding=hub_target_binding
+            )
+        from fdai_deployment_cli.source_recovery import (
+            recovered_application_evidence,
+            resume_source_installation,
+        )
+
+        if interactive or confirm_initial or installation_options is not None:
+            raise ValueError("source recovery cannot replace the retained initial scope or prompt")
+        if operational_evidence_verifier_input is not None:
+            raise ValueError("source recovery cannot add a new operational evidence verifier input")
+        if notification_recipients is not None:
+            raise ValueError("source recovery cannot add notification recipients")
+        if development_authority_profile is not None:
+            raise ValueError("source recovery cannot add a development authority profile")
+        if clear_development_authority_profile:
+            raise ValueError("source recovery cannot clear a development authority profile")
+        work_dir = work_dir.absolute()
+        foundation_recovery_directory = foundation_recovery_directory.absolute()
+        progress = resume_source_installation(
+            source_root=source_root,
+            work_dir=work_dir,
+            recovery_directory=foundation_recovery_directory,
+            runtime_profile=runtime_profile,
+            region=region,
+            monthly_cost_ceiling=monthly_cost_ceiling,
+            timeout_seconds=timeout_seconds,
+            approval_file=approval_file,
+        )
+        if hub_target_binding is not None and progress.get("target_binding") != hub_target_binding:
+            raise ValueError("Hub request target differs from retained Foundation recovery")
+        if progress.get("stage") != "application-plan":
+            return progress
+        evidence = recovered_application_evidence(
+            work_dir=work_dir,
+            recovery_directory=foundation_recovery_directory,
+            progress=progress,
+            runtime_profile_digest=runtime_profile.digest,
+            region=region,
+            monthly_cost_ceiling=monthly_cost_ceiling,
+        )
+        execution_source = inspect_source(source_root)
+        prepared_source = SimpleNamespace(
+            root=work_dir / "foundation",
+            ssh_private_key=work_dir / "foundation/runner_ed25519",
+            target_binding=progress["target_binding"],
+            source_commit=progress["source_commit"],
+            run_binding=evidence.run_binding,
+        )
+        application = complete_application(
+            kit=None,
+            prepared=prepared_source,
+            status=evidence.status,
+            scripts=execution_source.root / "scripts/deployment/azure",
+            deadline=DeploymentDeadline(timeout_seconds),
+            selected_runtime=runtime_profile,
+            trial_token=None,
+            application_state_adoption=None,
+            foundation_state_receipt_digest=evidence.state_handoff_digest,
+            catalog_review_profile=CatalogReviewDeploymentProfile.unselected(),
+            current_operator_object_id=current_operator_object_id,
+            source_snapshot=work_dir / "source-snapshot",
+            source_snapshot_digest=evidence.source_snapshot_digest,
+            source_root=execution_source.root,
+            foundation_recovery_directory=foundation_recovery_directory,
+            hub_selection=hub_selection,
+        )
+        return {
+            **application,
+            "foundation_recovery_receipt_digest": progress["foundation_receipt_digest"],
+            "source_recovery_progress_digest": progress["receipt_digest"],
+            "recovery_execution_source_commit": progress["execution_source_commit"],
+        }
+    deadline = DeploymentDeadline(timeout_seconds)
+    begin_stage("discovery")
+    with installer_activity("Preparing the clean source snapshot"):
+        prepared = prepare_source_deployment(
+            source_root=source_root,
+            work_dir=work_dir,
+            runtime_profile=runtime_profile,
+            region=region,
+            monthly_cost_ceiling=monthly_cost_ceiling,
+            hub_selection_digest=hub_selection.digest if hub_selection is not None else None,
+        )
+    with installer_activity("Verifying source and tenant-local identity names"):
+        source = inspect_source(source_root, expected_commit=str(prepared["source_commit"]))
+        _require_unique_entra_display_names(
+            runtime_profile,
+            source.root / "scripts/deployment/azure",
+            target_binding=current_target_binding(timeout_seconds=deadline.remaining(60)),
+        )
+    with installer_activity("Checking AKS SKU, quota, and PostgreSQL availability"):
+        preflight = inspect_aks_target(
+            profile=runtime_profile,
+            region=region,
+            timeout_seconds=deadline.remaining(180),
+            owned_resource_group=_retained_application_group(work_dir, foundation_workload),
+        )
+    if hub_target_binding is not None and preflight.get("target_binding") != hub_target_binding:
+        raise ValueError("Azure target changed after the Hub deployment request")
+    work_dir = work_dir.absolute()
+    retained_binding = {
+        "source_commit": source.commit,
+        "target_binding": preflight.get("target_binding"),
+    }
+    if preflight["state"] != "feasible" and not started_installation_matches(
+        work_dir,
+        retained_binding,
+    ):
+        return {**preflight, "stage": "aks-preflight"}
+    if installation_options is not None:
+        progress_detail("Waiting for the one-time installation scope confirmation")
+        confirmation = confirm_installation_scope(
+            work_dir=work_dir,
+            binding={
+                "source_commit": source.commit,
+                "target_binding": preflight["target_binding"],
+                "preparation_digest": prepared["receipt_digest"],
+                "runtime_profile_digest": runtime_profile.digest,
+                "region": region,
+                "monthly_cost_ceiling": monthly_cost_ceiling,
+            },
+            runtime_profile=runtime_profile,
+            options=installation_options,
+            interactive=confirm_initial,
+            timeout_seconds=deadline.remaining(86400),
+        )
+        source.reverify()
+        if confirmation["state"] != "confirmed":
+            return {**confirmation, "source_commit": source.commit}
+    with installer_activity("Checking the public compute estimate"):
+        cost_review = inspect_aks_compute_cost(
+            profile=runtime_profile,
+            region=region,
+            monthly_cost_ceiling=monthly_cost_ceiling,
+            timeout_seconds=deadline.remaining(120),
+        )
+    source.reverify()
+    if cost_review["state"] == "blocked":
+        return {**cost_review, "source_commit": source.commit}
+    tools = work_dir / "source-tools"
+    tools.mkdir(mode=0o700, exist_ok=True)
+    terraform = tools / "terraform"
+    toolchain = load_json_object(
+        (source.root / "infra/genesis-runner-image/toolchain.json").read_bytes(),
+        label="source toolchain",
+    )
+    digest = toolchain.get("terraform_binary_sha256")
+    with installer_activity("Preparing the checksum-pinned Terraform executable"):
+        if terraform.exists():
+            if hashlib.sha256(terraform.read_bytes()).hexdigest() != digest:
+                raise ValueError("retained source Terraform differs; preserve the run")
+        else:
+            installed = shutil.which("terraform")
+            try:
+                if installed is None:
+                    raise ValueError("no Terraform on PATH")
+                _copy_terraform(Path(installed), terraform, expected_digest=digest)
+            except (OSError, ValueError):
+                download_pinned_terraform(
+                    toolchain=toolchain,
+                    destination=terraform,
+                    timeout_seconds=deadline.remaining(300),
+                )
+    scripts = source.root / "scripts/deployment/azure"
+    foundation = work_dir / "foundation"
+    begin_stage("foundation")
+    progress_detail("Preparing Foundation inputs and the retained execution context")
+    environment = {
+        key: value
+        for key, value in os.environ.items()
+        if key
+        in {"HOME", "PATH", "AZURE_CONFIG_DIR", "LANG", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE"}
+    }
+    environment["PYTHONPATH"] = str(source.root / "packages/deployment-cli/src")
+    preparation = _capture(
+        (
+            sys.executable,
+            str(scripts / "source_genesis.py"),
+            "--work-dir",
+            str(foundation),
+            "--source-commit",
+            source.commit,
+            "--target-binding",
+            str(preflight["target_binding"]),
+            "--region",
+            region,
+            "--monthly-cost-ceiling",
+            str(monthly_cost_ceiling),
+            "--workload",
+            foundation_workload,
+            "--register-providers",
+        ),
+        source.root,
+        environment,
+        deadline.remaining(900),
+    )
+    values = load_json_object(
+        read_private_bytes(foundation / "foundation-variables.json", max_bytes=65536),
+        label="source Foundation variables",
+    )
+    environment["AZURE_SUBSCRIPTION_ID"] = str(values["subscription_id"])
+    environment["AZURE_TENANT_ID"] = str(values["tenant_id"])
+    run_binding = preparation.get("run_binding")
+    if not isinstance(run_binding, str):
+        raise ValueError(  # noqa: TRY004 - stable CLI invariant error, not caller type misuse
+            "source Foundation preparation has no retained run binding"
+        )
+    approval = (
+        approval_file.absolute()
+        if approval_file is not None
+        else foundation / "current-source-approval.json"
+    )
+    status_path = foundation / "status.json"
+    failed_advance_recovery_used = False
+    while True:
+        source.reverify()
+        previous = prior_attempt(status_path)
+        try:
+            result = _capture(
+                (
+                    sys.executable,
+                    str(scripts / "source_genesis.py"),
+                    "--advance",
+                    "--work-dir",
+                    str(foundation),
+                    "--source-commit",
+                    source.commit,
+                    "--target-binding",
+                    str(preflight["target_binding"]),
+                    "--region",
+                    region,
+                    "--monthly-cost-ceiling",
+                    str(monthly_cost_ceiling),
+                    "--workload",
+                    foundation_workload,
+                    "--register-providers",
+                    "--source-snapshot",
+                    str(work_dir / "source-snapshot"),
+                    "--source-snapshot-digest",
+                    str(prepared["source_snapshot_digest"]),
+                    "--terraform",
+                    str(terraform),
+                    "--timeout-seconds",
+                    str(deadline.remaining(14400)),
+                    *(
+                        ("--approval-file", str(approval))
+                        if approval_file is not None
+                        or ((interactive or selected_source() is not None) and approval.exists())
+                        else ()
+                    ),
+                ),
+                source.root,
+                environment,
+                deadline.remaining(14400),
+            )
+        except ValueError:
+            if failed_advance_recovery_used or not _claimed_foundation_apply_requires_recovery(
+                foundation
+            ):
+                raise
+            failed_advance_recovery_used = True
+            progress_detail("Recovering the claimed Foundation apply without repeating its effect")
+            continue
+        source.reverify()
+        if (
+            result.get("schema_version") != "fdai.source-foundation-progress.v1"
+            or result.get("state") != "review"
+            or result.get("source_commit") != source.commit
+            or result.get("run_binding") != run_binding
+            or result.get("provenance") != "operator-selected-source"
+            or result.get("release_signature_verified") is not False
+            or result.get("apply_authorized") is not False
+            or type(result.get("mutation_performed")) is not bool
+            or result.get("deployment_ready") is not False
+        ):
+            raise ValueError("source Foundation did not return a bound review result")
+        status = current_status(
+            status_path, previous=previous, source_commit=source.commit, run_binding=run_binding
+        )
+        if (
+            result.get("attempt") != status["attempt"]
+            or result.get("stage") != status.get("current_stage")
+            or result["mutation_performed"] != status.get("mutation_performed")
+        ):
+            raise ValueError("source Foundation progress differs from its current status")
+        if result["stage"] == "application-plan":
+            report = status.get("foundation_report")
+            handoff = report.get("state_handoff") if isinstance(report, dict) else None
+            plan = report.get("foundation_plan") if isinstance(report, dict) else None
+            plan_ref = plan.get("plan_ref") if isinstance(plan, dict) else None
+            completed = status.get("completed_stages")
+            if (
+                not isinstance(handoff, dict)
+                or not isinstance(plan_ref, str)
+                or re.fullmatch(r"foundation-plan-attempt-[1-9][0-9]*", plan_ref) is None
+            ):
+                raise ValueError("source application transfer requires verified Foundation handoff")
+            expected_handoff_digest = handoff.get("receipt_digest")
+            handoff = load_json_object(
+                read_private_bytes(
+                    foundation / plan_ref / "foundation-state-handoff-receipt.json",
+                    max_bytes=1024 * 1024,
+                ),
+                label="source Foundation handoff receipt",
+                max_bytes=1024 * 1024,
+            )
+            if (
+                status.get("route") != "private-runner"
+                or not isinstance(completed, list)
+                or "foundation-state" not in completed
+                or not isinstance(handoff, dict)
+                or handoff.get("schema_version")
+                != "fdai.genesis-foundation-state-handoff-receipt.v1"
+                or handoff.get("state") != "verified"
+                or handoff.get("source_commit") != source.commit
+                or handoff.get("target_binding") != preflight["target_binding"]
+                or any(
+                    handoff.get(key) is not True
+                    for key in (
+                        "effect_verified",
+                        "runner_attested",
+                        "remote_backend_authority_verified",
+                        "zero_change_verified",
+                        "remote_transient_deleted",
+                    )
+                )
+            ):
+                raise ValueError("source application transfer requires verified Foundation handoff")
+            from fdai_deployment_cli.contracts import canonical_digest
+
+            if (
+                canonical_digest(
+                    {key: value for key, value in handoff.items() if key != "receipt_digest"}
+                )
+                != expected_handoff_digest
+                or handoff.get("receipt_digest") != expected_handoff_digest
+            ):
+                raise ValueError("source Foundation handoff digest differs")
+            prepared_source = SimpleNamespace(
+                root=foundation,
+                ssh_private_key=foundation / "runner_ed25519",
+                target_binding=preflight["target_binding"],
+                source_commit=source.commit,
+                run_binding=run_binding,
+            )
+            application = complete_application(
+                kit=None,
+                prepared=prepared_source,
+                status=status,
+                scripts=scripts,
+                deadline=deadline,
+                selected_runtime=runtime_profile,
+                trial_token=None,
+                application_state_adoption=None,
+                foundation_state_receipt_digest=str(expected_handoff_digest),
+                catalog_review_profile=CatalogReviewDeploymentProfile.unselected(),
+                operational_evidence_verifier_input=operational_evidence_verifier_input,
+                notification_recipients=notification_recipients,
+                development_authority_profile=development_authority_profile,
+                clear_development_authority_profile=clear_development_authority_profile,
+                current_operator_object_id=current_operator_object_id,
+                source_snapshot=work_dir / "source-snapshot",
+                source_snapshot_digest=str(prepared["source_snapshot_digest"]),
+                source_root=source.root,
+                hub_selection=hub_selection,
+            )
+            return {**application, "cost_review": cost_review}
+        if (not interactive and selected_source() is None) or result["stage"] not in {
+            "runner-image-apply",
+            "foundation-apply",
+            "runner-enrollment",
+            "foundation-state",
+        }:
+            return {**result, "cost_review": cost_review}
+        approval.unlink(missing_ok=True)
+        if selected_source() is not None:
+            sys.path.insert(0, str(scripts))
+            try:
+                approval_prompt = importlib.import_module("genesis_approval_prompt")
+                approval_prompt.approve_status(status_path, approval)
+            finally:
+                sys.path.remove(str(scripts))
+            continue
+        prompt = subprocess.run(
+            (
+                sys.executable,
+                str(scripts / "genesis_approval_prompt.py"),
+                "--status",
+                str(status_path),
+                "--output",
+                str(approval),
+            ),
+            cwd=source.root,
+            env=environment,
+            stdout=sys.stderr,
+            check=False,
+            timeout=deadline.remaining(600),
+        )
+        if prompt.returncode != 0:
+            raise ValueError("source Foundation exact approval was not granted")
+
+
+def _retained_application_group(work_dir: Path, workload: str) -> str | None:
+    """Name the resource group a resumed run already owns, from its retained variables."""
+
+    path = work_dir.absolute() / "foundation" / "foundation-variables.json"
+    if not path.is_file() or path.is_symlink():
+        return None
+    try:
+        values = load_json_object(
+            read_private_bytes(path, max_bytes=65536), label="retained Foundation variables"
+        )
+    except (OSError, ValueError):
+        return None
+    region_short = values.get("region_short")
+    if (
+        values.get("workload") != workload
+        or not isinstance(region_short, str)
+        or re.fullmatch(r"[a-z][a-z0-9]{1,11}", region_short) is None
+        or re.fullmatch(r"[a-z][a-z0-9-]{1,30}", workload) is None
+    ):
+        return None
+    return f"rg-{workload}-dev-{region_short}"
+
+
+def _capture(
+    command: tuple[str, ...], root: Path, environment: dict[str, str], timeout: int
+) -> dict[str, object]:
+    result = subprocess.run(
+        command,
+        cwd=root,
+        env=environment,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=sys.stderr,
+        check=False,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        raise ValueError(
+            "source planning stage failed; preserve private state and do not repeat effects"
+        )
+    return load_json_object(result.stdout, label="source planning result", max_bytes=1024 * 1024)
+
+
+def _claimed_foundation_apply_requires_recovery(foundation: Path) -> bool:
+    claims = sorted(foundation.glob("foundation-plan-attempt-*/foundation-apply-claim.json"))
+    if len(claims) != 1 or claims[0].is_symlink():
+        return False
+    receipt = claims[0].with_name("foundation-apply-receipt.json")
+    return not receipt.exists() and not receipt.is_symlink()
+
+
+def _require_unique_entra_display_names(
+    profile: RuntimeDeploymentProfile,
+    scripts: Path,
+    *,
+    target_binding: str,
+) -> None:
+    product = profile.product_profile
+    if not (
+        product.selects(ProductAddOn.READ_ONLY_CONSOLE)
+        or product.selects(ProductAddOn.ENTERPRISE_IDENTITY_GOVERNANCE)
+    ):
+        return
+    sys.path.insert(0, str(scripts))
+    try:
+        genesis_entra = importlib.import_module("genesis_entra")
+        spa_display_name = genesis_entra.scoped_spa_display_name(target_binding)
+        check = getattr(genesis_entra, "check_unique_display_names", None)
+        if callable(check):
+            check(spa_display_name=spa_display_name)
+            return
+        plan_entra = getattr(genesis_entra, "plan_entra", None)
+        if callable(plan_entra):
+            plan_entra(spa_display_name=spa_display_name)
+    finally:
+        sys.path.remove(str(scripts))

fdai_deployment_cli/source_change_cli.py

@@ -0,0 +1,107 @@
+"""CLI adapters for changed-source planning, execution, and timing evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from fdai_deployment_cli.deployment_progress import DeploymentProgress
+from fdai_deployment_cli.private_output import write_private_output
+from fdai_deployment_cli.source_change_plan import plan_git_changes
+from fdai_deployment_cli.source_changed_update import deploy_changed_source
+from fdai_deployment_cli.source_service_update import deploy_source_service_update
+from fdai_deployment_cli.source_service_update_cli import source_service_update_inputs
+
+PrintMapping = Callable[..., None]
+
+
+def provision_plan(args: argparse.Namespace, print_mapping: PrintMapping) -> int:
+    result = plan_git_changes(args.source, args.base, args.head)
+    print_mapping(
+        result,
+        output=args.output,
+        text=(
+            f"source change lane: {result['lane']}; "
+            f"reason={result['reason_code']}; no deployment performed"
+        ),
+    )
+    return 0
+
+
+def provision_update(
+    args: argparse.Namespace,
+    print_mapping: PrintMapping,
+    *,
+    deploy: Callable[..., dict[str, object]] = deploy_changed_source,
+) -> int:
+    result = deploy(
+        source_root=args.source,
+        base=args.base,
+        application_work_dir=args.application_work_dir,
+        work_dir=args.work_dir,
+        timeout_seconds=args.timeout_seconds,
+    )
+    services = result.get("services")
+    if not isinstance(services, list) or any(not isinstance(item, str) for item in services):
+        raise ValueError("source changed update returned an invalid service list")
+    print_mapping(
+        result,
+        output=args.output,
+        text=f"source changed update: {result['state']}; services={','.join(services) or 'none'}",
+    )
+    return 0 if result["state"] in {"applied", "no-deploy"} else 2
+
+
+def provision_service_update(args: argparse.Namespace) -> int:
+    source, application, selected, development_profile, clear_development_profile = (
+        source_service_update_inputs(args)
+    )
+    result = deploy_source_service_update(
+        source_root=source,
+        application_work_dir=application,
+        work_dir=selected,
+        service=args.service,
+        timeout_seconds=args.timeout_seconds,
+        adopt_historical_binding=args.adopt_historical_binding,
+        adopt_historical_state=args.adopt_historical_state,
+        adopt_historical_variables=args.adopt_historical_variables,
+        adopt_historical_live=args.adopt_historical_live,
+        adopt_historical_plan=args.adopt_historical_plan,
+        development_authority_profile=development_profile,
+        clear_development_authority_profile=clear_development_profile,
+    )
+    print(
+        json.dumps(result, sort_keys=True, separators=(",", ":"))
+        if args.output == "json"
+        else f"source service update applied: {result['service']} at {result['source_commit']}"
+    )
+    return 0
+
+
+def attach_timing(
+    result: Mapping[str, Any],
+    *,
+    progress: DeploymentProgress,
+    work_dir: Path,
+) -> dict[str, Any]:
+    timing = progress.timing_receipt(
+        lane="source-install",
+        outcome=str(result.get("state", "unknown")),
+        recorded_at=datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+    )
+    timing_directory = work_dir / "timing"
+    timing_directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    timing_path = timing_directory / f"{timing['receipt_digest']}.json"
+    if not timing_path.exists():
+        write_private_output(
+            timing_path,
+            json.dumps(timing, sort_keys=True, separators=(",", ":")) + "\n",
+        )
+    return {**result, "timing_receipt_digest": timing["receipt_digest"]}
+
+
+__all__ = ["attach_timing", "provision_plan", "provision_service_update", "provision_update"]