korvid 0.1.2__tar.gz

korvid-0.1.2/.claude/hooks/protect-files.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+PROTECTED=("uv.lock" ".github/workflows/" "tach.toml" ".pre-commit-config.yaml")
+for pattern in "${PROTECTED[@]}"; do
+  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
+    echo "Blocked: $FILE_PATH is a protected gate file — ask the human to change it" >&2
+    exit 2
+  fi
+done
+exit 0

korvid-0.1.2/.claude/settings.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "file=$(jq -r '.tool_input.file_path // empty'); if echo \"$file\" | grep -q '\\.py$'; then uv run ruff check --fix --quiet \"$file\" 2>/dev/null; uv run ruff format --quiet \"$file\" 2>/dev/null; fi; exit 0"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run pytest -x -q --tb=short 2>&1 | tail -20"
+          }
+        ]
+      }
+    ]
+  }
+}

korvid-0.1.2/.github/dependabot.yml

@@ -0,0 +1,76 @@
+version: 2
+
+updates:
+  # Python dependencies, resolved through uv.lock.
+  #
+  # Runtime vulnerabilities already fail CI: the `security` job audits the
+  # locked runtime resolution with pip-audit. Nothing audits the dev group,
+  # because dev packages do not ship in the wheel - but they do run in CI
+  # with the repository checked out, and nine GitPython advisories sat open
+  # because an alert with no path to a pull request is not a process.
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    ignore:
+      # mcp 2.0 is a breaking release: the Server type parameters, the
+      # registration surface, `request_context`, the Tool schema field name
+      # and the streamable_http_client return arity all changed. That
+      # migration touches the path the approval gate sits on, so it is
+      # tracked as #260 rather than done as a bump. Remove this entry in
+      # the same change that closes it.
+      - dependency-name: mcp
+        update-types: [version-update:semver-major]
+    groups:
+      # One pull request per group keeps the review loop bounded: a routine
+      # dev-tool bump does not deserve the same attention as a runtime one.
+      #
+      # Grouped by name rather than by `dependency-type`: the uv updater
+      # reports every dependency as production, so a development group would
+      # match nothing and the runtime group would quietly absorb the dev
+      # tools it exists to separate. The runtime list is the project
+      # dependencies plus every extra - keep it in step with pyproject.toml.
+      runtime:
+        patterns:
+          - textual
+          - kubernetes_asyncio
+          - kubernetes-asyncio
+          - pyyaml
+          - rich
+          - regex
+          - httpx
+          - keyring
+          - mcp
+          - anyio
+          - starlette
+          - uvicorn
+          - azure-identity
+      dev-tooling:
+        patterns: ["*"]
+        exclude-patterns:
+          - textual
+          - kubernetes_asyncio
+          - kubernetes-asyncio
+          - pyyaml
+          - rich
+          - regex
+          - httpx
+          - keyring
+          - mcp
+          - anyio
+          - starlette
+          - uvicorn
+          - azure-identity
+
+  # Action pins. Every `uses:` in this repository is pinned to a commit SHA,
+  # which is what makes a supply-chain review meaningful and also what makes
+  # the pins invisible to a human reader - they cannot tell a current pin
+  # from a two-year-old one without looking each up.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

korvid-0.1.2/.github/scripts/wait-aks-settled.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Wait until the AKS cluster has no operation in flight.
+#
+# Azure flips `powerState.code` as soon as it accepts a start/stop request,
+# while `provisioningState` stays Starting/Stopping/Updating until the
+# operation actually completes. Any other operation issued in that window is
+# rejected with "there's an in-progress ... operation", so both the start and
+# the stop paths have to wait for the real thing.
+#
+# Usage: wait-aks-settled.sh <resource-group> <cluster> [expected-power-state]
+#
+# Exits 0 once provisioningState is Succeeded (and, when given, powerState
+# matches). Exits 1 if that has not happened within WAIT_AKS_TIMEOUT seconds
+# (default 600), printing the last observed pair.
+#
+# Query failures are retried through the whole budget by default, because the
+# caller after a stop is a barrier: giving up early would release the
+# workflow's concurrency group while the stop is still in flight, which is the
+# collision this exists to prevent. Set WAIT_AKS_MAX_QUERY_FAILURES to abort
+# after N consecutive failures instead - only appropriate for an advisory
+# pre-flight check whose failure does not skip anything.
+set -uo pipefail
+
+group=${1:?resource group required}
+cluster=${2:?cluster name required}
+want_power=${3:-}
+max_fails=${WAIT_AKS_MAX_QUERY_FAILURES:-0}
+
+deadline=$(( SECONDS + ${WAIT_AKS_TIMEOUT:-600} ))
+power=""
+prov=""
+fails=0
+err_file=$(mktemp)
+trap 'rm -f "$err_file"' EXIT
+
+while :; do
+  if out=$(az aks show -g "$group" -n "$cluster" \
+      --query '[powerState.code,provisioningState]' -o tsv 2>"$err_file"); then
+    fails=0
+    read -r power prov < <(printf '%s' "$out" | tr '\n' ' ') || true
+  else
+    # An expired login, a wrong subscription or a deleted cluster is
+    # permanent, so every failure is logged rather than hidden. Whether to
+    # give up early is the caller's call: a barrier must keep waiting, since
+    # returning early would release the concurrency group with an operation
+    # still running.
+    fails=$(( fails + 1 ))
+    power=""
+    prov=""
+    echo "az aks show failed: $(tr '\n' ' ' <"$err_file")"
+    if [ "$max_fails" -gt 0 ] && [ "$fails" -ge "$max_fails" ]; then
+      echo "::error title=Cluster query failed::az aks show failed $fails times in a row for $cluster: $(tr '\n' ' ' <"$err_file")"
+      exit 1
+    fi
+  fi
+  if [ "${prov:-}" = "Succeeded" ] && { [ -z "$want_power" ] || [ "${power:-}" = "$want_power" ]; }; then
+    exit 0
+  fi
+  case "${prov:-}" in
+    Failed|Canceled)
+      # Terminal: nothing is in flight, so polling to the deadline would only
+      # delay the report and then blame the wrong thing.
+      echo "::error title=Cluster in a terminal state::$cluster provisioningState=$prov (power=${power:-unknown}); no operation is in flight."
+      exit 1
+      ;;
+  esac
+  # Poll once more *at* the deadline rather than sleeping past it and failing
+  # on a stale read: an operation that settles during the final sleep still
+  # counts as settled within the advertised budget.
+  [ "$SECONDS" -lt "$deadline" ] || break
+  echo "waiting for $cluster to settle (${power:-unknown}/${prov:-unknown})"
+  sleep 20
+done
+
+echo "::error title=Cluster busy::$cluster is ${power:-unknown}/${prov:-unknown} after ${WAIT_AKS_TIMEOUT:-600}s; another operation has not finished."
+exit 1

korvid-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# Supersede a PR's older runs when new commits arrive. Non-PR events get a
+# unique group: GitHub cancels a *pending* run when a newer one joins the
+# group even with cancel-in-progress off, so sharing a group on main would
+# let a burst of merges discard the middle commit's verification.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # Docs are load-bearing for the suite - tests assert README, SECURITY.md,
+  # docs/keybindings.md and docs/windows.md still match the code and the
+  # release workflow - so a docs edit must still be tested. It does not need
+  # testing four times: those contracts are not Python-version or OS
+  # specific. Classify the change here so the redundant legs can skip the
+  # 20-30 minute pytest step while still reporting (they are required checks,
+  # and a required check that never runs blocks the merge forever).
+  changes:
+    runs-on: ubuntu-latest
+    # Reading the PR's file list needs more than the workflow-level
+    # `contents: read`; without this the API call 404s on every PR.
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      code: ${{ steps.classify.outputs.code }}
+    steps:
+      - name: Classify the change
+        id: classify
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -uo pipefail
+          # Fail closed: anything we cannot positively identify as docs-only
+          # gets the full matrix. That includes a failed API call - exiting
+          # non-zero here would *skip* the dependent test jobs rather than run
+          # them, and a skipped required check never reports.
+          if [ -z "${PR:-}" ]; then
+            echo "code=true" >> "$GITHUB_OUTPUT"
+            echo "not a pull request; running everything"
+            exit 0
+          fi
+          if ! files=$(gh api --paginate "repos/$REPO/pulls/$PR/files" --jq '.[].filename'); then
+            echo "code=true" >> "$GITHUB_OUTPUT"
+            echo "could not read the file list; running everything"
+            exit 0
+          fi
+          echo "$files"
+          # Docs-only means every path is under docs/ or is a root .md file.
+          # grep must consume the whole list: `grep -q` stops at the first hit
+          # and SIGPIPEs the writer, which under pipefail fails the pipeline
+          # and would read as docs-only - skipping tests on a code change.
+          non_docs=$(printf '%s\n' "$files" | { grep -cvE '^(docs/.*|[^/]+\.md)$' || true; })
+          if [ "${non_docs:-1}" -gt 0 ]; then
+            echo "code=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "code=false" >> "$GITHUB_OUTPUT"
+            echo "docs-only: one full test pass instead of four"
+          fi
+
+  test:
+    needs: changes
+    runs-on: korvid-runners
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --dev --all-extras
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy
+      - run: uv run tach check
+      - run: uvx deptry src/
+      # A docs-only change still gets a full suite run, on one version.
+      - if: needs.changes.outputs.code == 'true' || matrix.python-version == '3.12'
+        run: uv run pytest --cov --cov-fail-under=80
+
+  windows-test:
+    needs: changes
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --locked --dev --all-extras
+      # Windows verifies OS-specific behaviour; docs contracts are not that.
+      - if: needs.changes.outputs.code == 'true'
+        run: uv run pytest -q
+
+  pre-commit:
+    runs-on: korvid-runners
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked --dev --all-extras
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+
+  security:
+    runs-on: korvid-runners
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: true
+      # Dependency vulnerability audit against the locked resolution.
+      # --all-extras, because `korvid[agent]` and `korvid[mcp]` are supported
+      # installs: auditing the base set alone leaves an httpx or starlette
+      # advisory invisible until release verification catches it.
+      - run: uv export --frozen --all-extras --no-emit-project --no-dev -o requirements.txt
+      - run: uvx pip-audit -r requirements.txt --disable-pip
+      # Static analysis of GitHub Actions workflows themselves
+      - run: uvx zizmor --min-severity medium .github/workflows/
+
+  dependency-review:
+    if: github.event_name == 'pull_request'
+    runs-on: korvid-runners
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294  # v5.0.0
+        with:
+          fail-on-severity: high
+
+  ty-experimental:
+    runs-on: korvid-runners
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+      - run: uvx ty check src/ || true

korvid-0.1.2/.github/workflows/codeql.yml

@@ -0,0 +1,33 @@
+name: CodeQL
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 4 * * 1"
+
+permissions:
+  contents: read
+
+# Same policy as CI: supersede a PR's older analyses, and keep every
+# push/schedule analysis in its own group so a queued one is never displaced.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  analyze:
+    runs-on: korvid-runners
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6
+        with:
+          languages: python
+          queries: security-extended
+      - uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3  # v4.37.6

korvid-0.1.2/.github/workflows/k8s-contract.yml

@@ -0,0 +1,286 @@
+name: K8s contract tests
+# Live-cluster contract suite (issue #109). Runs the destructive
+# write-path contract tests against the dedicated, stopped-at-rest
+# AKS cluster `aks-korvid-contract-test`. Never runs for pull requests
+# or forks: the Azure identity is scoped to the protected
+# `aks-contract-test` environment, which only `main` may use.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: korvid-k8s-contract
+  cancel-in-progress: false
+
+env:
+  # The one cluster this workflow is allowed to touch. The guard steps
+  # fail closed when the (mutable) environment variables drift from
+  # these fixed, documented test-only names.
+  EXPECTED_RESOURCE_GROUP: rg-korvid-contract-test
+  EXPECTED_CLUSTER_NAME: aks-korvid-contract-test
+
+jobs:
+  contract:
+    # GitHub-hosted ephemeral runner — deliberately NOT the shared
+    # self-hosted `korvid-runners` pool, so cluster credentials never
+    # touch persistent shared infrastructure.
+    runs-on: ubuntu-latest
+    environment: aks-contract-test
+    timeout-minutes: 45
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      AKS_RESOURCE_GROUP: ${{ vars.AKS_RESOURCE_GROUP }}
+      AKS_CLUSTER_NAME: ${{ vars.AKS_CLUSTER_NAME }}
+      # Named only in the guard's repair hint. Fixed rather than a variable so
+      # a drifting setting cannot send someone to scale the system pool.
+      WORKLOAD_NODEPOOL: workload
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Guard — refuse any target other than the documented test cluster
+        run: |
+          if [ "$AKS_RESOURCE_GROUP" != "$EXPECTED_RESOURCE_GROUP" ] || \
+             [ "$AKS_CLUSTER_NAME" != "$EXPECTED_CLUSTER_NAME" ]; then
+            echo "::error title=Cluster identity mismatch::environment variables point at $AKS_RESOURCE_GROUP/$AKS_CLUSTER_NAME, expected $EXPECTED_RESOURCE_GROUP/$EXPECTED_CLUSTER_NAME. Refusing to run destructive tests."
+            exit 1
+          fi
+
+      - uses: azure/login@f5d393ae46f8fde4be8b75f32e3fc50e654ad0ca # v3.0.1
+        with:
+          client-id: ${{ vars.AZURE_CLIENT_ID }}
+          tenant-id: ${{ vars.AZURE_TENANT_ID }}
+          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Guard — verify test-only tags before touching the cluster
+        run: |
+          purpose=$(az aks show -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" \
+            --query 'tags.purpose' -o tsv)
+          production=$(az aks show -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" \
+            --query 'tags."production-use"' -o tsv)
+          if [ "$purpose" != "korvid-contract-testing" ] || [ "$production" != "prohibited" ]; then
+            echo "::error title=Not a test-only cluster::$AKS_CLUSTER_NAME is missing the purpose=korvid-contract-testing / production-use=prohibited tags. Refusing to run destructive tests."
+            exit 1
+          fi
+
+      - name: Start AKS cluster
+        run: |
+          # A preceding run's stop can still be finishing even though
+          # powerState already reads Stopped; Azure rejects a start until it
+          # settles. Not a barrier - failing here fails this job and cleanup
+          # still runs - so give up early on a broken query rather than
+          # burning ten minutes on it.
+          WAIT_AKS_MAX_QUERY_FAILURES=3 \
+            .github/scripts/wait-aks-settled.sh "$AKS_RESOURCE_GROUP" "$AKS_CLUSTER_NAME"
+          state=$(az aks show -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" --query powerState.code -o tsv)
+          if [ "$state" != "Running" ]; then
+            az aks start -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME"
+          fi
+
+      - uses: azure/use-kubelogin@0ce7c36141aa27d4934872cf00b0120804c98a29 # v1.3
+        with:
+          kubelogin-version: v0.2.15
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Fetch user credentials (no --admin, isolated kubeconfig)
+        run: |
+          export KUBECONFIG="$RUNNER_TEMP/contract-kubeconfig"
+          az aks get-credentials -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" \
+            --overwrite-existing -f "$KUBECONFIG"
+          kubelogin convert-kubeconfig -l azurecli --kubeconfig "$KUBECONFIG"
+          chmod 600 "$KUBECONFIG"
+          echo "KUBECONFIG=$KUBECONFIG" >> "$GITHUB_ENV"
+
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv sync --locked --dev --all-extras
+
+      - name: Install helm
+        run: |
+          HELM_VERSION=v3.19.0
+          curl -fsSL "https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz" \
+            | tar -xz -C "$RUNNER_TEMP" linux-amd64/helm
+          sudo install "$RUNNER_TEMP/linux-amd64/helm" /usr/local/bin/helm
+
+      - name: Janitor — remove stale fixtures from interrupted runs
+        run: uv run python -m tests.contract.janitor
+
+      - name: Guard — a schedulable disposable node must exist
+        run: |
+          set -euo pipefail
+          # The suite needs one node that satisfies both of its requirements at
+          # once: the node-operation contracts only touch
+          # korvid.dev/disposable=true and fail closed rather than fall back to
+          # a system node, while every test pod carries a
+          # korvid.dev/pool=workload nodeSelector. Those labels riding the same
+          # node is a convention of the pool setup, not something enforced
+          # here, so both are required together — a node with only one of them
+          # would let this guard pass and leave pods Pending.
+          #
+          # With no such node the suite produces six failures across four files
+          # — "no disposable workload node found" and pod-scheduling timeouts —
+          # none of which names the cause. It stayed red for eight commits.
+          #
+          # Asked of the cluster rather than of Azure: a stopped or
+          # still-starting cluster reports agentPools[].count as 0 even when
+          # the pool is populated, so the control-plane number is not evidence.
+          #
+          # Checked, not repaired: the workflow identity holds a deliberately
+          # minimal role with agentPools/read and no write, and widening it so
+          # this job could scale the pool would also let it reshape the system
+          # pool that every other guard here exists to protect.
+          SELECTOR=korvid.dev/disposable=true,korvid.dev/pool=workload
+
+          # Prove the node list is reachable first. Otherwise an expired token,
+          # an RBAC denial, or an unreachable API server spends the whole
+          # deadline and then blames an empty pool, sending the reader after a
+          # scale command that cannot help.
+          if ! nodes=$(kubectl get nodes -o name 2>&1); then
+            echo "::error title=Cannot query nodes::Listing nodes on $AKS_CLUSTER_NAME failed, so the disposable-node check could not run: $nodes"
+            exit 1
+          fi
+
+          # `kubectl wait` requires *every* node matching the selector to
+          # satisfy the condition, but this guard needs only one somewhere to
+          # schedule. A second pool node, or one cycling through an image
+          # upgrade, would otherwise burn the whole deadline and report "no
+          # schedulable node" while a perfectly good one was sitting there.
+          #
+          # Ready alone is not enough: a crashed node-ops test leaves the node
+          # cordoned, and a cordoned node would pass a Ready-only check and
+          # leave every test pod Pending. This runs after the janitor, which
+          # uncordons disposable nodes, so anything still cordoned here is
+          # something the janitor could not fix and a human has to look at.
+          deadline=$(( SECONDS + 300 ))
+          while :; do
+            if kubectl get nodes -l "$SELECTOR" \
+              -o jsonpath='{range .items[*]}{.metadata.name}{"=ready:"}{range .status.conditions[?(@.type=="Ready")]}{.status}{end}{" unschedulable:"}{.spec.unschedulable}{"\n"}{end}' \
+              2>/dev/null | grep -q '=ready:True unschedulable:$'; then
+              kubectl get nodes -l "$SELECTOR"
+              exit 0
+            fi
+            [ "$SECONDS" -lt "$deadline" ] || break
+            sleep 5
+          done
+          echo "::error title=No schedulable disposable node::$AKS_CLUSTER_NAME has no Ready, uncordoned node matching $SELECTOR after 5 minutes, so the node-operation and resize contracts have nowhere to schedule. If a previous run left the node cordoned, uncordon it. If the $WORKLOAD_NODEPOOL pool is empty, restore it by starting the cluster first — this run's cleanup job stops it, and Azure rejects every operation except start on a stopped cluster: az aks start -g $AKS_RESOURCE_GROUP -n $AKS_CLUSTER_NAME && az aks nodepool scale -g $AKS_RESOURCE_GROUP --cluster-name $AKS_CLUSTER_NAME -n $WORKLOAD_NODEPOOL --node-count 1 && az aks stop -g $AKS_RESOURCE_GROUP -n $AKS_CLUSTER_NAME"
+          kubectl get nodes -o wide --show-labels || true
+          exit 1
+
+      - name: Run contract suite
+        timeout-minutes: 30
+        env:
+          KORVID_CONTRACT_RUN_ID: ${{ github.run_id }}-${{ github.run_attempt }}
+        run: uv run pytest -p no:randomly -m contract tests/contract/ -v
+
+      - name: Collect diagnostics
+        if: failure() || cancelled()
+        run: |
+          mkdir -p diag
+          kubectl get events -A --sort-by=.lastTimestamp > diag/events.txt || true
+          kubectl get pods -A -o wide > diag/pods.txt || true
+          kubectl describe pods -A > diag/pods-describe.txt || true
+          kubectl get nodes -o wide > diag/nodes.txt || true
+          kubectl get ns -l app.kubernetes.io/managed-by=korvid-contract -o yaml > diag/namespaces.yaml || true
+
+      - name: Upload diagnostics
+        if: failure() || cancelled()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: contract-diagnostics
+          path: diag/
+          retention-days: 14
+
+      - name: Delete kubeconfig
+        if: always()
+        run: |
+          if [ -n "${KUBECONFIG:-}" ] && [ -f "$KUBECONFIG" ]; then
+            rm -f "$KUBECONFIG"
+          fi
+
+  # Separate job so the stop runs even when the contract job hits its
+  # timeout-minutes (GitHub kills the job before later always() steps,
+  # which would leave the stopped-at-rest cluster running and billing).
+  stop-cluster:
+    needs: contract
+    if: always()
+    runs-on: ubuntu-latest
+    environment: aks-contract-test
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      AKS_RESOURCE_GROUP: ${{ vars.AKS_RESOURCE_GROUP }}
+      AKS_CLUSTER_NAME: ${{ vars.AKS_CLUSTER_NAME }}
+    steps:
+      # The settle helper lives in the repo, so this job needs the tree too.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Guard — refuse any target other than the documented test cluster
+        run: |
+          if [ "$AKS_RESOURCE_GROUP" != "$EXPECTED_RESOURCE_GROUP" ] || \
+             [ "$AKS_CLUSTER_NAME" != "$EXPECTED_CLUSTER_NAME" ]; then
+            echo "::error title=Cluster identity mismatch::environment variables point at $AKS_RESOURCE_GROUP/$AKS_CLUSTER_NAME, expected $EXPECTED_RESOURCE_GROUP/$EXPECTED_CLUSTER_NAME. Refusing to stop an unexpected cluster."
+            exit 1
+          fi
+
+      - uses: azure/login@f5d393ae46f8fde4be8b75f32e3fc50e654ad0ca # v3.0.1
+        with:
+          client-id: ${{ vars.AZURE_CLIENT_ID }}
+          tenant-id: ${{ vars.AZURE_TENANT_ID }}
+          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Stop AKS cluster
+        run: |
+          # A test may have left an operation in flight (a nodepool scale, a
+          # failed run mid-write) and Azure would reject the stop outright.
+          # Advisory only: it must never prevent the stop, because a step that
+          # dies here leaves the cluster running with no recovery hint - so a
+          # failed or timed-out wait falls through and lets the stop try
+          # anyway, and its own error is the report.
+          WAIT_AKS_TIMEOUT=300 WAIT_AKS_MAX_QUERY_FAILURES=3 \
+          .github/scripts/wait-aks-settled.sh "$AKS_RESOURCE_GROUP" "$AKS_CLUSTER_NAME" \
+          || echo "cluster did not settle before the stop; attempting it anyway"
+          # Azure rejects a stop on a cluster that is not running, which is the
+          # normal state when the contract job failed before starting it.
+          state=$(az aks show -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" --query powerState.code -o tsv 2>/dev/null || echo unknown)
+          if [ "$state" = "Stopped" ]; then
+          echo "$AKS_CLUSTER_NAME is already stopped"
+          elif ! az aks stop -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" --no-wait; then
+          # The state read above can be `unknown` when the query itself
+          # failed, so a rejection here may just mean it was already stopped.
+          # Check before crying wolf: a red cleanup job for a cluster that is
+          # costing nothing trains people to ignore this error.
+          recheck=$(az aks show -g "$AKS_RESOURCE_GROUP" -n "$AKS_CLUSTER_NAME" --query powerState.code -o tsv 2>/dev/null || echo unknown)
+          if [ "$recheck" = "Stopped" ]; then
+            echo "$AKS_CLUSTER_NAME was already stopped"
+          else
+            echo "::error title=AKS stop rejected::aks-korvid-contract-test would not accept a stop and reads $recheck; idle compute may be accruing. Stop it manually once its current operation finishes: az aks stop -g $AKS_RESOURCE_GROUP -n $AKS_CLUSTER_NAME"
+            exit 1
+          fi
+          fi
+          # powerState flips to Stopped as soon as Azure accepts the request,
+          # while provisioningState stays Stopping until the operation really
+          # finishes. Waiting on powerState alone let this job exit seconds
+          # after asking, so the next merge's run hit "there's an in-progress
+          # stop managed cluster operation" on its own start. This one is a
+          # barrier, so it retries query failures through the whole budget.
+          if ! WAIT_AKS_TIMEOUT=600 .github/scripts/wait-aks-settled.sh \
+            "$AKS_RESOURCE_GROUP" "$AKS_CLUSTER_NAME" Stopped; then
+          echo "::error title=AKS stop failed::aks-korvid-contract-test did not settle at Stopped; idle compute may be accruing. Stop it manually: az aks stop -g $AKS_RESOURCE_GROUP -n $AKS_CLUSTER_NAME"
+          exit 1
+          fi