feat: trigger rolling releases on code-only deploys via source fingerprint (#320)

* feat(build): add compute_source_fingerprint for code change detection

Computes a SHA-256 fingerprint of user source files during build.
Deterministic, content-sensitive, path-sensitive, and order-independent.
Used to detect code-only changes that should trigger rolling releases.

* feat(build): write source_fingerprint into manifest during build

Calls compute_source_fingerprint after manifest builder produces the
manifest dict, injecting the hex digest before writing to disk.

* feat(deployment): inject source fingerprint into resource env during reconciliation

Code-only changes (no resource config diff) previously took the reuse
path and never triggered a rolling release. Injecting the source
fingerprint computed at build time into each resource's env field means
a code change produces a diff in the comparison JSON, routing to the
update path and triggering a rolling release.

- Inject _FLASH_SOURCE_FINGERPRINT into resource env before comparison
- No-op when source_fingerprint absent (backward compatibility)
- Three tests: fingerprint changed triggers update, unchanged takes
  reuse path, missing fingerprint falls back to config-only comparison

* fix: address QA feedback on source fingerprint PR

- Move hashlib import to module level (consistency with file conventions)
- Add comment clarifying intentional local_manifest mutation in reconciliation
- Assert injected fingerprint value and user env var preservation in test

* fix: address Copilot feedback on fingerprint framing and test isolation

- Normalize paths to POSIX form so Windows and Unix builds of the same
  project produce the same fingerprint
- Add length-prefix framing to fingerprint hash input to eliminate
  theoretical path/content concatenation ambiguity
- Restructure test so the fingerprint value is the only diff between
  local and state manifests, proving the injection drives the update

Author: deanq

src/runpod_flash/cli/commands/build.py

@@ -1,6 +1,7 @@
 """Flash build command - Package Flash applications for deployment."""
 
 import ast
+import hashlib
 import importlib.util
 import json
 import logging
@@ -37,6 +38,36 @@
 
 console = Console()
 
+
+def compute_source_fingerprint(project_dir: Path, files: list[Path]) -> str:
+    """Compute a SHA-256 fingerprint of project source files.
+
+    Produces a deterministic hash that changes if and only if the user's
+    source files change. Used to detect code-only changes that should
+    trigger a rolling release even when resource config is unchanged.
+
+    Args:
+        project_dir: Project root for computing relative paths.
+        files: List of source file paths (from get_file_tree).
+
+    Returns:
+        Hex digest of the SHA-256 hash.
+    """
+    h = hashlib.sha256()
+    # Normalize to POSIX form so Windows and POSIX builds of the same project
+    # produce the same fingerprint. Use length-prefix framing between path and
+    # content to prevent concatenation ambiguity (e.g., rel='a'+content='bc'
+    # vs rel='ab'+content='c' would otherwise collide).
+    for f in sorted(files, key=lambda p: p.relative_to(project_dir).as_posix()):
+        rel_bytes = f.relative_to(project_dir).as_posix().encode("utf-8")
+        file_bytes = f.read_bytes()
+        h.update(len(rel_bytes).to_bytes(8, "big"))
+        h.update(rel_bytes)
+        h.update(len(file_bytes).to_bytes(8, "big"))
+        h.update(file_bytes)
+    return h.hexdigest()
+
+
 # Constants
 # Timeout for pip install operations (large packages like torch can take 5-10 minutes)
 PIP_INSTALL_TIMEOUT_SECONDS = 600
@@ -307,6 +338,9 @@ def run_build(
                 python_version=python_version,
             )
             manifest = manifest_builder.build()
+            manifest["source_fingerprint"] = compute_source_fingerprint(
+                project_dir, files
+            )
             manifest_path = build_dir / "flash_manifest.json"
             manifest_path.write_text(json.dumps(manifest, indent=2))
 

src/runpod_flash/cli/utils/deployment.py

@@ -283,6 +283,16 @@ async def reconcile_and_provision_resources(
     actions = []
     manifest_python_version = local_manifest.get("python_version")
 
+    # Inject source fingerprint into each resource's env so that code-only
+    # changes (no resource config diff) still trigger a rolling release.
+    # The fingerprint is computed during flash build from user source files.
+    # Mutation intentional: persisted to state manifest via update_build_manifest below.
+    source_fingerprint = local_manifest.get("source_fingerprint")
+    if source_fingerprint:
+        for resource_config in local_manifest.get("resources", {}).values():
+            env = resource_config.setdefault("env", {})
+            env["_FLASH_SOURCE_FINGERPRINT"] = source_fingerprint
+
     # Provision new resources
     for resource_name in sorted(to_provision):
         resource_config = local_manifest["resources"][resource_name]

tests/unit/cli/commands/test_build.py

@@ -865,3 +865,76 @@ def mock_run(cmd, **kwargs):
                 break
         else:
             pytest.fail("--python-version not found in pip command")
+
+
+class TestComputeSourceFingerprint:
+    """Tests for compute_source_fingerprint function."""
+
+    def test_deterministic_output(self, tmp_path):
+        """Same files produce same hash across calls."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        f1 = tmp_path / "app.py"
+        f1.write_text("print('hello')")
+        f2 = tmp_path / "utils.py"
+        f2.write_text("x = 1")
+
+        files = [f1, f2]
+        hash1 = compute_source_fingerprint(tmp_path, files)
+        hash2 = compute_source_fingerprint(tmp_path, files)
+        assert hash1 == hash2
+        assert len(hash1) == 64  # SHA-256 hex digest length
+
+    def test_content_sensitive(self, tmp_path):
+        """Changing file content changes the hash."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        f1 = tmp_path / "app.py"
+        f1.write_text("print('hello')")
+        hash1 = compute_source_fingerprint(tmp_path, [f1])
+
+        f1.write_text("print('world')")
+        hash2 = compute_source_fingerprint(tmp_path, [f1])
+        assert hash1 != hash2
+
+    def test_path_sensitive(self, tmp_path):
+        """Renaming a file (same content) changes the hash."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        f1 = tmp_path / "app.py"
+        f1.write_text("content")
+        hash1 = compute_source_fingerprint(tmp_path, [f1])
+
+        f2 = tmp_path / "main.py"
+        f2.write_text("content")
+        hash2 = compute_source_fingerprint(tmp_path, [f2])
+        assert hash1 != hash2
+
+    def test_order_independent(self, tmp_path):
+        """Shuffled input order produces same hash (function sorts internally)."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        f1 = tmp_path / "a.py"
+        f1.write_text("aaa")
+        f2 = tmp_path / "b.py"
+        f2.write_text("bbb")
+
+        hash1 = compute_source_fingerprint(tmp_path, [f1, f2])
+        hash2 = compute_source_fingerprint(tmp_path, [f2, f1])
+        assert hash1 == hash2
+
+    def test_empty_file_list(self, tmp_path):
+        """Empty file list returns a valid SHA-256 hash."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        result = compute_source_fingerprint(tmp_path, [])
+        assert len(result) == 64
+
+    def test_handles_binary_files(self, tmp_path):
+        """Binary files are hashed without error."""
+        from runpod_flash.cli.commands.build import compute_source_fingerprint
+
+        f1 = tmp_path / "data.bin"
+        f1.write_bytes(b"\x00\x01\x02\xff")
+        result = compute_source_fingerprint(tmp_path, [f1])
+        assert len(result) == 64

tests/unit/cli/utils/test_deployment.py

@@ -632,3 +632,211 @@ async def test_reconciliation_ignores_runtime_fields_in_config_comparison(tmp_pa
         await reconcile_and_provision_resources(app, "build-123", "dev", local_manifest)
 
     mock_manager.get_or_deploy_resource.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_source_fingerprint_injected_into_resource_env(tmp_path):
+    """Source fingerprint from manifest is injected into each resource's env.
+
+    Both manifests have identical config and env except for the fingerprint
+    value. This isolates the fingerprint as the sole driver of the update path.
+    """
+    import json
+
+    flash_dir = tmp_path / ".flash"
+    flash_dir.mkdir()
+
+    # Local and state manifests are structurally identical except for the
+    # fingerprint value in env. If any other field differs, the test would
+    # not prove the injection is what triggered the update.
+    local_manifest = {
+        "source_fingerprint": "new_fingerprint_abc",
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+                "env": {},
+            },
+            "lb_endpoint": {
+                "resource_type": "CpuLiveLoadBalancer",
+                "config": "same",
+                "env": {"USER_VAR": "value"},
+            },
+        },
+        "resources_endpoints": {},
+    }
+    (flash_dir / "flash_manifest.json").write_text(json.dumps(local_manifest))
+
+    state_manifest = {
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+                "env": {"_FLASH_SOURCE_FINGERPRINT": "old_fingerprint_000"},
+            },
+            "lb_endpoint": {
+                "resource_type": "CpuLiveLoadBalancer",
+                "config": "same",
+                "env": {
+                    "USER_VAR": "value",
+                    "_FLASH_SOURCE_FINGERPRINT": "old_fingerprint_000",
+                },
+            },
+        },
+        "resources_endpoints": {
+            "worker": "https://worker.api.runpod.ai",
+            "lb_endpoint": "https://lb.api.runpod.ai",
+        },
+    }
+
+    app = AsyncMock()
+    app.get_build_manifest = AsyncMock(return_value=state_manifest)
+    app.update_build_manifest = AsyncMock()
+
+    mock_resource = MagicMock()
+    mock_resource.endpoint_url = "https://new.api.runpod.ai"
+    mock_resource.endpoint_id = "new-endpoint-id"
+
+    with (
+        patch("pathlib.Path.cwd", return_value=tmp_path),
+        patch("runpod_flash.cli.utils.deployment.ResourceManager") as mock_manager_cls,
+        patch(
+            "runpod_flash.cli.utils.deployment.create_resource_from_manifest"
+        ) as mock_create_resource,
+    ):
+        mock_manager = MagicMock()
+        mock_manager.get_or_deploy_resource = AsyncMock(return_value=mock_resource)
+        mock_manager_cls.return_value = mock_manager
+        mock_create_resource.return_value = MagicMock()
+
+        await reconcile_and_provision_resources(
+            app, "build-123", "dev", local_manifest, show_progress=False
+        )
+
+    # Fingerprint is the only diff -> both resources should have been updated
+    assert mock_manager.get_or_deploy_resource.call_count == 2
+
+    # Verify injection overwrote the fingerprint with the new value
+    worker_env = local_manifest["resources"]["worker"]["env"]
+    assert worker_env["_FLASH_SOURCE_FINGERPRINT"] == "new_fingerprint_abc"
+
+    lb_env = local_manifest["resources"]["lb_endpoint"]["env"]
+    assert lb_env["_FLASH_SOURCE_FINGERPRINT"] == "new_fingerprint_abc"
+    # User-defined env vars preserved after injection
+    assert lb_env["USER_VAR"] == "value"
+
+
+@pytest.mark.asyncio
+async def test_source_fingerprint_unchanged_takes_reuse_path(tmp_path):
+    """When source fingerprint matches state, reuse path is taken (no update)."""
+    import json
+
+    flash_dir = tmp_path / ".flash"
+    flash_dir.mkdir()
+
+    local_manifest = {
+        "source_fingerprint": "same_fingerprint_abc",
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+            },
+        },
+        "resources_endpoints": {},
+    }
+    (flash_dir / "flash_manifest.json").write_text(json.dumps(local_manifest))
+
+    # State manifest has SAME fingerprint (code unchanged)
+    state_manifest = {
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+                "env": {"_FLASH_SOURCE_FINGERPRINT": "same_fingerprint_abc"},
+            },
+        },
+        "resources_endpoints": {
+            "worker": "https://worker.api.runpod.ai",
+        },
+    }
+
+    app = AsyncMock()
+    app.get_build_manifest = AsyncMock(return_value=state_manifest)
+    app.update_build_manifest = AsyncMock()
+
+    with (
+        patch("pathlib.Path.cwd", return_value=tmp_path),
+        patch("runpod_flash.cli.utils.deployment.ResourceManager") as mock_manager_cls,
+    ):
+        mock_manager = MagicMock()
+        mock_manager.get_or_deploy_resource = AsyncMock()
+        mock_manager_cls.return_value = mock_manager
+
+        await reconcile_and_provision_resources(
+            app, "build-123", "dev", local_manifest, show_progress=False
+        )
+
+    # Fingerprint unchanged -> reuse path, no provisioning
+    mock_manager.get_or_deploy_resource.assert_not_called()
+
+    # Endpoint info copied from state
+    assert (
+        local_manifest["resources_endpoints"]["worker"]
+        == "https://worker.api.runpod.ai"
+    )
+
+
+@pytest.mark.asyncio
+async def test_missing_source_fingerprint_backward_compatible(tmp_path):
+    """Manifests without source_fingerprint behave as before (reuse when config matches)."""
+    import json
+
+    flash_dir = tmp_path / ".flash"
+    flash_dir.mkdir()
+
+    # No source_fingerprint key -- older flash version
+    local_manifest = {
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+            },
+        },
+        "resources_endpoints": {},
+    }
+    (flash_dir / "flash_manifest.json").write_text(json.dumps(local_manifest))
+
+    state_manifest = {
+        "resources": {
+            "worker": {
+                "resource_type": "LiveServerless",
+                "config": "same",
+            },
+        },
+        "resources_endpoints": {
+            "worker": "https://worker.api.runpod.ai",
+        },
+    }
+
+    app = AsyncMock()
+    app.get_build_manifest = AsyncMock(return_value=state_manifest)
+    app.update_build_manifest = AsyncMock()
+
+    with (
+        patch("pathlib.Path.cwd", return_value=tmp_path),
+        patch("runpod_flash.cli.utils.deployment.ResourceManager") as mock_manager_cls,
+    ):
+        mock_manager = MagicMock()
+        mock_manager.get_or_deploy_resource = AsyncMock()
+        mock_manager_cls.return_value = mock_manager
+
+        await reconcile_and_provision_resources(
+            app, "build-123", "dev", local_manifest, show_progress=False
+        )
+
+    # No fingerprint -> no injection -> config matches -> reuse path
+    mock_manager.get_or_deploy_resource.assert_not_called()
+    assert (
+        local_manifest["resources_endpoints"]["worker"]
+        == "https://worker.api.runpod.ai"
+    )