@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/deployment/src/project_forge_deployment/app_runtime_remote.py

@@ -0,0 +1,416 @@
+"""Remote Bash template for generic application runtime deployment."""
+
+REMOTE_SCRIPT = r'''#!/usr/bin/env bash
+set -Eeuo pipefail
+
+ACTION="$1"
+EXPECTED_SPEC_SHA="${2:-}"
+DEPLOY_USER="${3:-}"
+APP_ROOT="__APP_ROOT__"
+APP_SCHEMA_VERSION="__APP_SCHEMA_VERSION__"
+NETWORK_NAME="__NETWORK_NAME__"
+CADDY_CONTAINER="__CADDY_CONTAINER__"
+DESIRED_PRESENT="__DESIRED_PRESENT__"
+
+D_OWNER_B64="__D_OWNER_B64__"
+D_ENV_B64="__D_ENV_B64__"
+D_APP_B64="__D_APP_B64__"
+D_CONTAINER_B64="__D_CONTAINER_B64__"
+D_IMAGE_B64="__D_IMAGE_B64__"
+D_PORT="__D_PORT__"
+D_HEALTH_B64="__D_HEALTH_B64__"
+D_RUN_AS_B64="__D_RUN_AS_B64__"
+D_PERSISTENCE="__D_PERSISTENCE__"
+D_DATA_TARGET_B64="__D_DATA_TARGET_B64__"
+D_SPEC_SHA="__D_SPEC_SHA__"
+D_ENV_KEYS=(__D_ENV_KEYS__)
+D_ENV_VALUES=(__D_ENV_VALUES__)
+
+b64d() { printf '%s' "$1" | base64 --decode; }
+meta_value() {
+    local path="$1" key="$2"
+    [[ -f "$path" ]] || return 1
+    sed -n "s/^${key}=//p" "$path" | head -n1
+}
+valid_slug() { [[ "$1" =~ ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ ]]; }
+valid_repo() { [[ "$1" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; }
+valid_container() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$ ]]; }
+valid_image() { [[ "$1" =~ ^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$ ]]; }
+valid_port() { [[ "$1" =~ ^[0-9]+$ ]] && (( 1 <= 10#$1 && 10#$1 <= 65535 )); }
+valid_run_as() { [[ "$1" =~ ^[0-9]+(:[0-9]+)?$ ]]; }
+valid_env_key() { [[ "$1" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; }
+
+platform_ready() {
+    [[ -f /srv/project-forge-platform/platform.env ]] &&
+    docker network inspect "$NETWORK_NAME" >/dev/null 2>&1 &&
+    [[ "$(docker inspect --format '{{.State.Status}}' "$CADDY_CONTAINER" 2>/dev/null || true)" == "running" ]]
+}
+
+network_has_container() {
+    local container="$1"
+    docker network inspect "$NETWORK_NAME" --format '{{range .Containers}}{{.Name}}{{"\n"}}{{end}}' 2>/dev/null |
+        grep -Fxq "$container"
+}
+
+probe_http() {
+    local container="$1" port="$2" path="$3"
+    docker exec "$CADDY_CONTAINER" \
+        wget -q -T 5 -O /dev/null "http://${container}:${port}${path}" >/dev/null 2>&1
+}
+
+wait_ready() {
+    local container="$1" port="$2" path="$3"
+    local deadline=$((SECONDS + 120)) state=""
+    while (( SECONDS < deadline )); do
+        state="$(docker inspect --format '{{.State.Status}}' "$container" 2>/dev/null || true)"
+        if [[ "$state" == "running" ]] && network_has_container "$container" && probe_http "$container" "$port" "$path"; then
+            return 0
+        fi
+        if [[ "$state" == "exited" || "$state" == "dead" ]]; then
+            return 1
+        fi
+        sleep 2
+    done
+    return 1
+}
+
+inventory() {
+    local count=0 state current previous release_file
+    local owner env app container image spec_sha port health persistence
+    local running connected healthy
+    if [[ -d "$APP_ROOT" ]]; then
+        while IFS= read -r state; do
+            [[ -n "$state" ]] || continue
+            owner="$(meta_value "$state" OWNER_REPO || true)"
+            env="$(meta_value "$state" ENVIRONMENT || true)"
+            app="$(meta_value "$state" APP_SLUG || true)"
+            current="$(meta_value "$state" CURRENT_RELEASE || true)"
+            previous="$(meta_value "$state" PREVIOUS_RELEASE || true)"
+            spec_sha="$(meta_value "$state" SPEC_SHA256 || true)"
+            [[ -n "$owner" && -n "$env" && -n "$app" && -n "$current" && -n "$spec_sha" ]] || {
+                echo "Managed application state is malformed: $state" >&2
+                exit 31
+            }
+            release_file="$(dirname "$state")/releases/$current/release.env"
+            [[ -f "$release_file" && ! -L "$release_file" ]] || {
+                echo "Current application release metadata is missing: $release_file" >&2
+                exit 31
+            }
+            container="$(meta_value "$release_file" CONTAINER_NAME || true)"
+            image="$(meta_value "$release_file" IMAGE || true)"
+            port="$(meta_value "$release_file" RUNTIME_PORT || true)"
+            health="$(b64d "$(meta_value "$release_file" HEALTH_PATH_B64 || true)")"
+            persistence="$(meta_value "$release_file" PERSISTENCE_MODE || true)"
+            [[ "$(meta_value "$release_file" SPEC_SHA256 || true)" == "$spec_sha" ]] || {
+                echo "Application state/release fingerprint mismatch: $state" >&2
+                exit 31
+            }
+            running=false
+            connected=false
+            healthy=false
+            [[ "$(docker inspect --format '{{.State.Status}}' "$container" 2>/dev/null || true)" == "running" ]] && running=true || true
+            network_has_container "$container" && connected=true || true
+            if [[ "$running" == true && "$connected" == true ]]; then
+                probe_http "$container" "$port" "$health" && healthy=true || true
+            fi
+            printf 'APP\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+                "$owner" "$env" "$app" "$container" "$image" "$spec_sha" "$port" "$health" "$persistence" \
+                "$current" "$previous" "$running" "$connected" "$healthy"
+            count=$((count + 1))
+        done < <(find "$APP_ROOT" -mindepth 3 -maxdepth 3 -type f -name deployment.env -print 2>/dev/null | sort)
+    fi
+    printf 'SUMMARY\tappCount\t%s\n' "$count"
+}
+
+configure_registry_auth() {
+    [[ -n "$DEPLOY_USER" ]] || { echo "Deployment account is required." >&2; exit 32; }
+    [[ "$DEPLOY_USER" =~ ^[A-Za-z_][A-Za-z0-9_.-]{0,31}$ ]] || {
+        echo "Deployment account contains unsupported characters." >&2
+        exit 32
+    }
+    local home config dir_mode file_mode deploy_uid
+    home="$(getent passwd "$DEPLOY_USER" | cut -d: -f6)"
+    [[ -n "$home" && "$home" == /* ]] || { echo "Could not resolve deployment account home." >&2; exit 32; }
+    config="$home/.docker"
+    if [[ ! -e "$config/config.json" ]]; then
+        return 0
+    fi
+    [[ -d "$config" && ! -L "$config" && -f "$config/config.json" && ! -L "$config/config.json" ]] || {
+        echo "Docker credential path is not a regular protected directory/file." >&2
+        exit 32
+    }
+    dir_mode="$(stat -c '%a' "$config")"
+    file_mode="$(stat -c '%a' "$config/config.json")"
+    deploy_uid="$(id -u "$DEPLOY_USER")"
+    if (( (8#$dir_mode & 077) != 0 || (8#$file_mode & 077) != 0 )) ||
+       [[ "$(stat -c '%u' "$config")" != "$deploy_uid" || "$(stat -c '%u' "$config/config.json")" != "$deploy_uid" ]]; then
+        echo "Docker credentials must be owned by the deployment account and deny group/other access." >&2
+        exit 32
+    fi
+    export DOCKER_CONFIG="$config"
+}
+
+decode_desired() {
+    [[ "$DESIRED_PRESENT" == true ]] || { echo "Deploy action omitted desired runtime spec." >&2; exit 33; }
+    D_OWNER="$(b64d "$D_OWNER_B64")"
+    D_ENV="$(b64d "$D_ENV_B64")"
+    D_APP="$(b64d "$D_APP_B64")"
+    D_CONTAINER="$(b64d "$D_CONTAINER_B64")"
+    D_IMAGE="$(b64d "$D_IMAGE_B64")"
+    D_HEALTH="$(b64d "$D_HEALTH_B64")"
+    D_RUN_AS="$(b64d "$D_RUN_AS_B64")"
+    D_DATA_TARGET="$(b64d "$D_DATA_TARGET_B64")"
+
+    valid_repo "$D_OWNER" || { echo "Invalid owner repository." >&2; exit 33; }
+    valid_slug "$D_ENV" || { echo "Invalid environment slug." >&2; exit 33; }
+    valid_slug "$D_APP" || { echo "Invalid application slug." >&2; exit 33; }
+    valid_container "$D_CONTAINER" || { echo "Invalid container name." >&2; exit 33; }
+    valid_image "$D_IMAGE" || { echo "Image is not an immutable sha256 digest reference." >&2; exit 33; }
+    valid_port "$D_PORT" || { echo "Invalid runtime port." >&2; exit 33; }
+    [[ "$D_HEALTH" == /* && "$D_HEALTH" != *$'\n'* && "$D_HEALTH" != *$'\r'* ]] || {
+        echo "Invalid health path." >&2
+        exit 33
+    }
+    valid_run_as "$D_RUN_AS" || { echo "Invalid numeric runAs value." >&2; exit 33; }
+    [[ "$D_PERSISTENCE" == "none" || "$D_PERSISTENCE" == "directory" ]] || {
+        echo "Invalid persistence mode." >&2
+        exit 33
+    }
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        [[ "$D_DATA_TARGET" == /* && "$D_DATA_TARGET" != *"/../"* && "$D_DATA_TARGET" != *$'\n'* ]] || {
+            echo "Invalid persistent data container path." >&2
+            exit 33
+        }
+    elif [[ -n "$D_DATA_TARGET" ]]; then
+        echo "Non-persistent runtime unexpectedly supplied a data path." >&2
+        exit 33
+    fi
+    [[ "$D_SPEC_SHA" =~ ^[0-9a-f]{64}$ ]] || { echo "Invalid runtime spec fingerprint." >&2; exit 33; }
+    [[ "${#D_ENV_KEYS[@]}" -eq "${#D_ENV_VALUES[@]}" ]] || { echo "Environment payload mismatch." >&2; exit 33; }
+
+    local index key
+    for index in "${!D_ENV_KEYS[@]}"; do
+        key="$(b64d "${D_ENV_KEYS[$index]}")"
+        valid_env_key "$key" || { echo "Invalid environment variable name." >&2; exit 33; }
+    done
+}
+
+release_value() {
+    meta_value "$1" "$2"
+}
+
+write_release_metadata() {
+    local release_file="$1"
+    local tmp="$release_file.tmp.$$" index key_b64 value_b64
+    {
+        printf 'SCHEMA_VERSION=%s\n' "$APP_SCHEMA_VERSION"
+        printf 'OWNER_REPO=%s\n' "$D_OWNER"
+        printf 'ENVIRONMENT=%s\n' "$D_ENV"
+        printf 'APP_SLUG=%s\n' "$D_APP"
+        printf 'CONTAINER_NAME=%s\n' "$D_CONTAINER"
+        printf 'IMAGE=%s\n' "$D_IMAGE"
+        printf 'RUNTIME_PORT=%s\n' "$D_PORT"
+        printf 'HEALTH_PATH_B64=%s\n' "$D_HEALTH_B64"
+        printf 'RUN_AS=%s\n' "$D_RUN_AS"
+        printf 'PERSISTENCE_MODE=%s\n' "$D_PERSISTENCE"
+        printf 'DATA_TARGET_B64=%s\n' "$D_DATA_TARGET_B64"
+        printf 'SPEC_SHA256=%s\n' "$D_SPEC_SHA"
+        printf 'ENV_COUNT=%s\n' "${#D_ENV_KEYS[@]}"
+        for index in "${!D_ENV_KEYS[@]}"; do
+            key_b64="${D_ENV_KEYS[$index]}"
+            value_b64="${D_ENV_VALUES[$index]}"
+            printf 'ENV_KEY_B64_%s=%s\n' "$index" "$key_b64"
+            printf 'ENV_VALUE_B64_%s=%s\n' "$index" "$value_b64"
+        done
+    } > "$tmp"
+    chmod 0600 "$tmp"
+    mv -f "$tmp" "$release_file"
+}
+
+start_desired_container() {
+    local root data
+    local uid gid index key value
+    root="$1"
+    data="$root/data"
+    uid="${D_RUN_AS%%:*}"
+    if [[ "$D_RUN_AS" == *:* ]]; then gid="${D_RUN_AS#*:}"; else gid="$uid"; fi
+
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        if [[ -L "$data" ]]; then
+            echo "Persistent data directory must not be a symbolic link." >&2
+            return 1
+        fi
+        if [[ ! -e "$data" ]]; then
+            install -d -m 0750 -o "$uid" -g "$gid" "$data"
+        elif [[ ! -d "$data" ]]; then
+            echo "Persistent data path is not a directory." >&2
+            return 1
+        elif [[ "$(stat -c '%u' "$data")" != "$uid" || "$(stat -c '%g' "$data")" != "$gid" ]]; then
+            echo "Persistent data directory ownership does not match runAs; use the persistence adapter/import path." >&2
+            return 1
+        fi
+    fi
+
+    local -a docker_args
+    docker_args=(
+        docker run -d
+        --name "$D_CONTAINER"
+        --restart unless-stopped
+        --network "$NETWORK_NAME"
+        --user "$D_RUN_AS"
+        --log-driver json-file
+        --log-opt max-size=10m
+        --log-opt max-file=3
+    )
+    if [[ "$D_PERSISTENCE" == "directory" ]]; then
+        docker_args+=(--mount "type=bind,src=$data,dst=$D_DATA_TARGET")
+    fi
+    for index in "${!D_ENV_KEYS[@]}"; do
+        key="$(b64d "${D_ENV_KEYS[$index]}")"
+        value="$(b64d "${D_ENV_VALUES[$index]}")"
+        docker_args+=(--env "$key=$value")
+    done
+    docker_args+=("$D_IMAGE")
+    "${docker_args[@]}" >/dev/null
+}
+
+record_evidence() {
+    local root="$1" outcome="$2" release_id="$3" previous="$4"
+    local timestamp
+    timestamp="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+    printf '{"timestamp":"%s","ownerRepo":"%s","environment":"%s","appSlug":"%s","container":"%s","image":"%s","specSha256":"%s","release":"%s","previousRelease":"%s","persistence":"%s","outcome":"%s"}\n' \
+        "$timestamp" "$D_OWNER" "$D_ENV" "$D_APP" "$D_CONTAINER" "$D_IMAGE" "$D_SPEC_SHA" \
+        "$release_id" "$previous" "$D_PERSISTENCE" "$outcome" >> "$root/deployment-evidence.jsonl"
+    chmod 0600 "$root/deployment-evidence.jsonl"
+}
+
+deploy() {
+    platform_ready || { echo "Kit shared platform is not ready." >&2; exit 34; }
+    decode_desired
+    configure_registry_auth
+
+    local root releases state current_release="" previous_release="" current_spec="" current_container="" next_previous=""
+    local digest release_id release_dir release_file lock_file tmp
+    root="$APP_ROOT/$D_APP/$D_ENV"
+    releases="$root/releases"
+    state="$root/deployment.env"
+    lock_file="/run/lock/project-forge-app-$D_APP--$D_ENV.lock"
+    digest="${D_IMAGE##*@sha256:}"
+    release_id="sha256-${digest}-${D_SPEC_SHA:0:16}"
+    release_dir="$releases/$release_id"
+    release_file="$release_dir/release.env"
+
+    exec 9>>"$lock_file"
+    if ! flock -n 9; then
+        echo "Another application deployment holds the lock for $D_APP--$D_ENV." >&2
+        exit 75
+    fi
+
+    for path in "$root" "$releases" "$state" "$root/data" "$root/deployment-evidence.jsonl"; do
+        [[ ! -L "$path" ]] || { echo "Managed application path must not be a symbolic link: $path" >&2; exit 35; }
+    done
+
+    if [[ -f "$state" ]]; then
+        [[ "$(meta_value "$state" OWNER_REPO || true)" == "$D_OWNER" &&
+           "$(meta_value "$state" ENVIRONMENT || true)" == "$D_ENV" &&
+           "$(meta_value "$state" APP_SLUG || true)" == "$D_APP" ]] || {
+            echo "Existing application state has different ownership." >&2
+            exit 35
+        }
+        current_release="$(meta_value "$state" CURRENT_RELEASE || true)"
+        previous_release="$(meta_value "$state" PREVIOUS_RELEASE || true)"
+        current_spec="$(meta_value "$state" SPEC_SHA256 || true)"
+        [[ -n "$current_release" && "$current_spec" =~ ^[0-9a-f]{64}$ ]] || {
+            echo "Existing application state is malformed." >&2
+            exit 35
+        }
+        [[ "$EXPECTED_SPEC_SHA" != "NONE" && "$current_spec" == "$EXPECTED_SPEC_SHA" ]] || {
+            echo "Application state changed after planning; create a fresh plan." >&2
+            exit 36
+        }
+        local current_file="$releases/$current_release/release.env"
+        [[ -f "$current_file" && ! -L "$current_file" ]] || {
+            echo "Current release metadata is missing." >&2
+            exit 35
+        }
+        current_container="$(release_value "$current_file" CONTAINER_NAME || true)"
+        valid_container "$current_container" || { echo "Current release container metadata is malformed." >&2; exit 35; }
+        if [[ "$current_spec" == "$D_SPEC_SHA" ]]; then
+            next_previous="$previous_release"
+        else
+            next_previous="$current_release"
+        fi
+    else
+        [[ "$EXPECTED_SPEC_SHA" == "NONE" ]] || {
+            echo "Application state disappeared after planning; create a fresh plan." >&2
+            exit 36
+        }
+    fi
+
+    if docker inspect "$D_CONTAINER" >/dev/null 2>&1 && [[ "$D_CONTAINER" != "$current_container" ]]; then
+        echo "Desired container name is already occupied outside this managed runtime." >&2
+        exit 37
+    fi
+
+    install -d -m 0750 "$APP_ROOT" "$APP_ROOT/$D_APP" "$root" "$releases"
+    if [[ -e "$release_dir" && ! -d "$release_dir" ]]; then
+        echo "Release path exists and is not a directory." >&2
+        exit 35
+    fi
+    install -d -m 0750 "$release_dir"
+    if [[ -f "$release_file" ]]; then
+        [[ "$(release_value "$release_file" SPEC_SHA256 || true)" == "$D_SPEC_SHA" ]] || {
+            echo "Release directory collision with different runtime metadata." >&2
+            exit 35
+        }
+    else
+        write_release_metadata "$release_file"
+    fi
+
+    docker pull "$D_IMAGE" >/dev/null
+
+    if [[ -n "$current_container" ]]; then
+        docker rm -f "$current_container" >/dev/null
+    fi
+
+    if ! start_desired_container "$root"; then
+        docker rm -f "$D_CONTAINER" >/dev/null 2>&1 || true
+        record_evidence "$root" "failed-start" "$release_id" "$current_release"
+        echo "Application container failed to start; previous release metadata was retained but runtime rollback was not attempted." >&2
+        exit 38
+    fi
+    if ! wait_ready "$D_CONTAINER" "$D_PORT" "$D_HEALTH"; then
+        docker rm -f "$D_CONTAINER" >/dev/null 2>&1 || true
+        record_evidence "$root" "failed-readiness" "$release_id" "$current_release"
+        echo "Application failed readiness; previous release metadata was retained but runtime rollback was not attempted." >&2
+        exit 39
+    fi
+
+    tmp="$state.tmp.$$"
+    {
+        printf 'SCHEMA_VERSION=%s\n' "$APP_SCHEMA_VERSION"
+        printf 'OWNER_REPO=%s\n' "$D_OWNER"
+        printf 'ENVIRONMENT=%s\n' "$D_ENV"
+        printf 'APP_SLUG=%s\n' "$D_APP"
+        printf 'CURRENT_RELEASE=%s\n' "$release_id"
+        printf 'PREVIOUS_RELEASE=%s\n' "$next_previous"
+        printf 'SPEC_SHA256=%s\n' "$D_SPEC_SHA"
+    } > "$tmp"
+    chmod 0600 "$tmp"
+    mv -f "$tmp" "$state"
+    record_evidence "$root" "deployed" "$release_id" "$next_previous"
+}
+
+case "$ACTION" in
+    inventory)
+        inventory
+        ;;
+    deploy)
+        deploy
+        ;;
+    *)
+        echo "Unsupported application-runtime action: $ACTION" >&2
+        exit 2
+        ;;
+esac
+'''

package/assets/generated/deployment/src/project_forge_deployment/app_runtime_workstation.py

@@ -0,0 +1,136 @@
+"""Remote application deployment using an exact image transferred from the workstation."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+from .app_runtime import (
+    NETWORK_NAME,
+    _find_app,
+    _inventory_snapshot,
+    app_inventory,
+    build_remote_script,
+)
+from .box_platform import platform_status
+from .errors import DeploymentKitError
+from .image_transfer import transfer_image
+from .profiles import load_profile
+from .ssh import ssh_args, verify_access
+
+
+def _preloaded_script(spec: dict[str, Any]) -> str:
+    script = build_remote_script(spec)
+    registry_block = "    decode_desired\n    configure_registry_auth\n"
+    if registry_block not in script:
+        raise DeploymentKitError("Application runtime template no longer contains the expected registry-auth hook.")
+    script = script.replace(registry_block, "    decode_desired\n", 1)
+    pull = '    docker pull "$D_IMAGE" >/dev/null\n'
+    replacement = '''    if ! docker image inspect "$D_IMAGE" >/dev/null 2>&1; then
+        echo "Exact application image was not preloaded by the workstation-mediated deployment path." >&2
+        exit 40
+    fi
+'''
+    if pull not in script:
+        raise DeploymentKitError("Application runtime template no longer contains the expected image-pull hook.")
+    return script.replace(pull, replacement, 1)
+
+
+def _run_preloaded_deploy(
+    profile: dict[str, Any],
+    address: str,
+    spec: dict[str, Any],
+    expected_spec_sha: str,
+) -> None:
+    command = ssh_args(
+        profile,
+        address,
+        command="sudo -n bash -s -- deploy " + (expected_spec_sha or "NONE") + " " + profile["user"],
+    )
+    completed = subprocess.run(
+        command,
+        input=_preloaded_script(spec).encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    if completed.returncode != 0:
+        stdout = completed.stdout.decode("utf-8", errors="replace")
+        stderr = completed.stderr.decode("utf-8", errors="replace")
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Workstation-mediated remote application deployment failed: {detail}")
+
+
+def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "targetName",
+        "action",
+        "environment",
+        "appSlug",
+        "ownerRepo",
+        "containerName",
+        "image",
+        "runtimePort",
+        "healthPath",
+        "persistenceMode",
+        "changeType",
+        "previousImage",
+        "previousRelease",
+        "retainsPreviousRelease",
+        "publishesHostPort",
+        "attachesSharedNetwork",
+        "modifiesRoutes",
+        "persistentDataDeletion",
+        "inventorySnapshot",
+        "expectedSpecSha256",
+        "spec",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
+        raise DeploymentKitError("Malformed application deployment plan.")
+
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+
+    transfer_image(plan["targetName"], plan["image"])
+
+    # Image transfer can take time. Re-check the material app/platform evidence before
+    # changing runtime state; a changed plan must never ride through on stale approval.
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory changed while transferring the image; create and authorize a fresh plan."
+        )
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform changed while transferring the image; deployment is blocked.")
+
+    profile = load_profile(plan["targetName"])
+    evidence = verify_access(profile)
+    _run_preloaded_deploy(
+        profile,
+        evidence["address"],
+        plan["spec"],
+        plan["expectedSpecSha256"] or "",
+    )
+
+    final = app_inventory(plan["targetName"])
+    deployed = _find_app(final, plan["appSlug"], plan["environment"])
+    if deployed is None:
+        raise DeploymentKitError("Application deployment returned without managed runtime state.")
+    if deployed["specSha256"] != plan["spec"]["specSha256"]:
+        raise DeploymentKitError("Application deployment returned with a different runtime spec.")
+    if not (
+        deployed["containerRunning"]
+        and deployed["connectedToSharedNetwork"]
+        and deployed["httpHealthy"]
+    ):
+        raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
+    final["mutated"] = True
+    final["imageSource"] = "workstation-transfer"
+    final["attachesSharedNetwork"] = NETWORK_NAME
+    return final