Report when the deployed policyengine.py version went live

.github/scripts/deploy_cloud_run_candidate.sh

@@ -7,6 +7,10 @@ cloud_run_set_defaults
 
 bash .github/scripts/validate_cloud_run_deploy_env.sh
 
+# DEPLOYED_POLICYENGINE_VERSION and POLICYENGINE_VERSION_LIVE_SINCE, reported
+# by GET /deployment.
+live_since_vars="$(bash .github/scripts/resolve_policyengine_live_since.sh)"
+
 env_vars=(
   "APP_ENVIRONMENT=${DEPLOYMENT_ENVIRONMENT}"
   "POLICYENGINE_DB_INSTANCE_CONNECTION_NAME=${POLICYENGINE_DB_INSTANCE_CONNECTION_NAME}"
@@ -48,6 +52,9 @@ env_vars=(
   "PUBLIC_API_AUTH_ISSUER=${PUBLIC_API_AUTH_ISSUER:-}"
   "PUBLIC_API_AUTH_AUDIENCE=${PUBLIC_API_AUTH_AUDIENCE:-}"
 )
+while IFS= read -r live_since_var; do
+  env_vars+=("${live_since_var}")
+done <<<"${live_since_vars}"
 
 # Optional: account deletion removes the Auth0 user only when the Management
 # API client is configured. Validation requires all three values or none.

.github/scripts/locked_packages.py

@@ -11,6 +11,7 @@
     locked_packages.py upgradeable LOCK  names it may upgrade, one per line
     locked_packages.py held LOCK         "name version" of each package it holds
     locked_packages.py summary OLD NEW   Markdown summary of the changes
+    locked_packages.py bundle-version LOCK  the locked .py bundle version
 """
 
 from __future__ import annotations
@@ -78,6 +79,25 @@ def held_versions(lock_path: Path) -> list[str]:
     ]
 
 
+def bundle_version(lock_path: Path) -> str:
+    """Return the one version of the .py bundle package that ``lock_path`` locks.
+
+    Raises:
+        SystemExit: when the bundle is locked at more than one version, since
+            the deploy could not say which one it installs.
+
+    """
+    versions, _ = _locked_versions(lock_path)
+    found = versions[BUNDLE_PACKAGE]
+    if len(found) != 1:
+        message = (
+            f"{BUNDLE_PACKAGE} is locked at {', '.join(found)} in {lock_path}; "
+            "expected exactly one version."
+        )
+        raise SystemExit(message)
+    return found[0]
+
+
 def summary(old_lock: Path, new_lock: Path) -> str:
     """Return a Markdown summary of the version changes from old_lock to new_lock."""
     old_versions, _ = _locked_versions(old_lock)
@@ -128,6 +148,7 @@ def main() -> None:
     commands = parser.add_subparsers(dest="command", required=True)
     commands.add_parser("upgradeable").add_argument("lock", type=Path)
     commands.add_parser("held").add_argument("lock", type=Path)
+    commands.add_parser("bundle-version").add_argument("lock", type=Path)
     summary_parser = commands.add_parser("summary")
     summary_parser.add_argument("old_lock", type=Path)
     summary_parser.add_argument("new_lock", type=Path)
@@ -137,6 +158,8 @@ def main() -> None:
         print("\n".join(upgradeable(arguments.lock)))
     elif arguments.command == "held":
         print("\n".join(held_versions(arguments.lock)))
+    elif arguments.command == "bundle-version":
+        print(bundle_version(arguments.lock))
     else:
         sys.stdout.write(summary(arguments.old_lock, arguments.new_lock))
 

.github/scripts/resolve_policyengine_live_since.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+
+# Decide when the policyengine.py (.py) version this deploy installs went live.
+# A deploy that keeps the serving revision's .py version keeps that revision's
+# date; a new .py version goes live with this deploy. The API redeploys several
+# times a day without changing .py, so a plain deploy time would not say how
+# long the version has been served.
+#
+# Inputs: PREVIOUS_CLOUD_RUN_REVISION (the revision serving 100% of traffic,
+# from capture_cloud_run_service_state.sh; empty on a first deploy) and the
+# usual CLOUD_RUN_* settings. POLICYENGINE_LOCK_FILE and
+# POLICYENGINE_LIVE_SINCE_NOW override the lock path and the clock for tests.
+#
+# Prints DEPLOYED_POLICYENGINE_VERSION=... and POLICYENGINE_VERSION_LIVE_SINCE=...
+# The date is recorded only when this deploy is the event (a new .py version
+# or a first deploy). When the serving revision has the same version but no
+# date (deployed before dates were recorded), or cannot be read, the date is
+# left empty (unknown) rather than set to a later, wrong time. A failed lookup
+# never fails the deploy.
+
+set -euo pipefail
+
+source .github/scripts/cloud_run_env.sh
+cloud_run_set_defaults
+
+lock_file="${POLICYENGINE_LOCK_FILE:-uv.lock}"
+# The same uv.lock reader the daily relock uses; it fails unless policyengine
+# is locked at exactly one version.
+version="$(python3 .github/scripts/locked_packages.py bundle-version "${lock_file}")"
+if [[ -z "${version}" ]]; then
+  echo "policyengine is not locked in ${lock_file}" >&2
+  exit 1
+fi
+
+now="${POLICYENGINE_LIVE_SINCE_NOW:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
+live_since="${now}"
+previous="${PREVIOUS_CLOUD_RUN_REVISION:-}"
+
+if [[ -n "${previous}" && "${CLOUD_RUN_DRY_RUN:-0}" != "1" ]]; then
+  gcloud_bin="${GCLOUD_BIN:-gcloud}"
+  if revision_json="$("${gcloud_bin}" run revisions describe "${previous}" \
+    --project "${CLOUD_RUN_PROJECT}" \
+    --region "${CLOUD_RUN_REGION}" \
+    --platform managed \
+    --format=json)"; then
+    revision_env() {
+      jq -r --arg name "$1" '
+        [.spec.containers[0].env[]? | select(.name == $name) | .value][0] // ""
+      ' <<<"${revision_json}" 2>/dev/null || true
+    }
+    previous_version="$(revision_env DEPLOYED_POLICYENGINE_VERSION)"
+    previous_since="$(revision_env POLICYENGINE_VERSION_LIVE_SINCE)"
+    if [[ "${previous_version}" == "${version}" ]]; then
+      live_since="${previous_since}"
+    elif [[ -z "${previous_version}" ]]; then
+      # A revision from before versions were recorded may already serve this
+      # version, so its start is unknown.
+      live_since=""
+    fi
+  else
+    echo "Could not read ${previous}; when .py ${version} went live is unknown" >&2
+    live_since=""
+  fi
+fi
+
+printf 'DEPLOYED_POLICYENGINE_VERSION=%s\nPOLICYENGINE_VERSION_LIVE_SINCE=%s\n' \
+  "${version}" "${live_since}"

.github/workflows/push.yml

@@ -308,6 +308,7 @@ jobs:
       - name: Deploy tagged Cloud Run staging candidate
         run: bash .github/scripts/deploy_cloud_run_candidate.sh
         env:
+          PREVIOUS_CLOUD_RUN_REVISION: ${{ steps.previous.outputs.revision }}
           CLOUD_RUN_IMAGE_TAG: ${{ steps.cloud_run.outputs.image_tag }}
           CLOUD_RUN_TAG: ${{ steps.cloud_run.outputs.revision_tag }}
           CLOUD_RUN_RUNTIME_SERVICE_ACCOUNT: policyengine-api-cr-staging@policyengine-api.iam.gserviceaccount.com
@@ -577,6 +578,7 @@ jobs:
       - name: Deploy tagged Cloud Run candidate
         run: bash .github/scripts/deploy_cloud_run_candidate.sh
         env:
+          PREVIOUS_CLOUD_RUN_REVISION: ${{ steps.previous.outputs.revision }}
           CLOUD_RUN_IMAGE_TAG: ${{ steps.cloud_run.outputs.image_tag }}
           CLOUD_RUN_TAG: ${{ steps.cloud_run.outputs.revision_tag }}
           CLOUD_RUN_RUNTIME_SERVICE_ACCOUNT: ${{ secrets.GCP_CLOUD_RUN_RUNTIME_SERVICE_ACCOUNT }}

changelog.d/added/4083.md

@@ -0,0 +1 @@
+`GET /deployment` reports the policyengine.py version the API serves and when it went live; the candidate deploy keeps that date across redeploys of the same version.

docs/engineering/migration-contracts.md

@@ -16,7 +16,7 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
 
 | Route group | Path segments | DB entity | Simulation flow |
 | --- | --- | --- | --- |
-| `health` | `health`, `simulation-gateway-check`, `liveness-check`, `readiness-check` | `none` | `none` |
+| `health` | `health`, `simulation-gateway-check`, `liveness-check`, `readiness-check`, `deployment` | `none` | `none` |
 | `specification` | `specification` | `none` | `none` |
 | `metadata` | `metadata`, `datasets`, `economy-options`, `parameter-values`, `parameters`, `regions`, `tax-benefit-model-versions`, `tax-benefit-models`, `variables` | `metadata` | `none` |
 | `policy` | `policy`, `policies`, `user-policy`, `user-policies` | `policy` | `none` |

docs/generated/migration_contracts.json

@@ -14,7 +14,8 @@
         "health",
         "simulation-gateway-check",
         "liveness-check",
-        "readiness-check"
+        "readiness-check",
+        "deployment"
       ],
       "sim_flow": null
     },

policyengine_api/fastapi_routes/health.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import os
+from importlib import metadata as importlib_metadata
 from typing import TYPE_CHECKING, Literal
 
 from fastapi import APIRouter, HTTPException
@@ -25,6 +27,20 @@ class SimulationGatewayHealthResponse(BaseModel):
     simulation_gateway: Literal["healthy"]
 
 
+class DeploymentResponse(BaseModel):
+    """The policyengine.py version this revision serves, and since when.
+
+    ``policyengine_version_live_since`` is when this .py version first went
+    live: redeploys that keep the version keep the date. It is null on a
+    revision deployed before the deploy recorded it, outside Cloud Run, or
+    when the version the deploy dated is not the installed one.
+    """
+
+    policyengine_version: str
+    policyengine_version_live_since: str | None
+    revision: str | None
+
+
 def build_core_health_router(
     dependencies: NativeRouteDependencies,
 ) -> APIRouter:
@@ -35,6 +51,21 @@ def build_core_health_router(
     def health() -> HealthResponse:
         return HealthResponse(status="healthy")
 
+    @router.get("/deployment", response_model=DeploymentResponse)
+    def deployment() -> DeploymentResponse:
+        installed = importlib_metadata.version("policyengine")
+        # The deploy computed the date for the version it read from uv.lock;
+        # it describes the installed version only when the two agree.
+        deployed = os.environ.get("DEPLOYED_POLICYENGINE_VERSION")
+        live_since = os.environ.get("POLICYENGINE_VERSION_LIVE_SINCE") or None
+        return DeploymentResponse(
+            policyengine_version=installed,
+            policyengine_version_live_since=(
+                live_since if deployed == installed else None
+            ),
+            revision=os.environ.get("K_REVISION") or None,
+        )
+
     @router.get(
         "/simulation-gateway-check",
         response_model=SimulationGatewayHealthResponse,

policyengine_api/migration_flags.py

@@ -51,6 +51,7 @@ class RouteImplementation(StrEnum):
     "/simulation-gateway-check": "health",
     "/liveness-check": "health",
     "/readiness-check": "health",
+    "/deployment": "health",
     "/specification": "specification",
     "/v2/openapi.json": "specification",
 }

policyengine_api/migration_registry.py

@@ -27,6 +27,7 @@ class RouteGroupConfig:
             "simulation-gateway-check",
             "liveness-check",
             "readiness-check",
+            "deployment",
         ),
     ),
     RouteGroupConfig(