feat(ci): add 3.14/3.15 base images and scenario exclude for downstream gate

Add RE2-safe list-scenarios -exclude and ci.yml test_scenarios_exclude so
wheel-only Python scenarios are not silently skipped. Ship Python 3.14/3.15
base images, dd-trace-py STS trigger policy, and migration gate index README.
Scenario workloads land in follow-up PRs.

Author: vlad-scherbich

.github/chainguard/dd-trace-py.github.trigger-ci.sts.yaml

@@ -0,0 +1,12 @@
+# Policy for: .github/workflows/prof-correctness.yml in DataDog/dd-trace-py
+# Allows dd-trace-py GitHub Actions to trigger prof-correctness workflows
+# when profiling code changes, to run correctness tests against just-built wheels.
+issuer: https://token.actions.githubusercontent.com
+subject_pattern: repo:DataDog/dd-trace-py:.*
+
+claim_pattern:
+  job_workflow_ref: DataDog/dd-trace-py/.github/workflows/prof-correctness.yml@refs/heads/.*
+  ref_type: branch
+
+permissions:
+  actions: write

.github/workflows/ci.yml

@@ -58,7 +58,15 @@ jobs:
   python:
     uses: ./.github/workflows/test.yml
     with:
-      test_scenarios: python.*
+      test_scenarios: 'python.*'
+      # Wheel-only scenarios need DDTRACE_INSTALL_URL (dd-trace-py downstream
+      # gate), so they can't run here against PyPI ddtrace: every *_3.15.
+      # python_downstream_gate is an index README, not a runnable scenario.
+      # Go's regexp is RE2 (no negative lookahead), so this is an explicit
+      # exclude rather than a lookahead baked into test_scenarios.
+      # Additional wheel-only 3.14 dirs (e.g. live_heap) are added to this list
+      # when those scenarios land.
+      test_scenarios_exclude: '_3\.15$|^python_downstream_gate$'
     secrets: inherit
   full_host:
     uses: ./.github/workflows/test.yml

.github/workflows/test.yml

@@ -9,6 +9,11 @@ on:
         required: false
         type: string
         default: '.*'
+      test_scenarios_exclude:
+        description: 'A regexp dropping scenarios matched by test_scenarios (RE2, unanchored)'
+        required: false
+        type: string
+        default: ''
       ddtrace_install_url:
         description: 'URL to a ddtrace install script (e.g. from S3 builds)'
         required: false
@@ -35,7 +40,7 @@ jobs:
         #   - free local-daemon layer caching: buildBaseImages runs once per chunk,
         #     and the chunk's scenarios reuse the built base image.
         run: |
-          matrix=$(go run ./cmd/list-scenarios -pattern '${{ inputs.test_scenarios }}' -chunk-size 3)
+          matrix=$(go run ./cmd/list-scenarios -pattern '${{ inputs.test_scenarios }}' -exclude '${{ inputs.test_scenarios_exclude }}' -chunk-size 3)
           echo "scenarios=$matrix" >> "$GITHUB_OUTPUT"
 
   docker-scenarios:

.gitignore

@@ -6,6 +6,7 @@ data/*
 __pycache__/
 
 .idea
+.vscode
 gems.locked
 
 .DS_Store

README.md

@@ -58,6 +58,27 @@ a step to analyze your results and match it against your expectation:
 You need to provide a JSON file with your expectations and a path to where to
 find the pprof files.
 
+## Downstream from dd-trace-py
+
+dd-trace-py triggers this repo after building wheels for a commit. The
+[`downstream-python.yml`](.github/workflows/downstream-python.yml) workflow
+installs ddtrace from the S3 wheel for that SHA (`DDTRACE_INSTALL_URL`) and
+runs selected Python scenarios.
+
+**Triggers (non-blocking):**
+
+| Source | When | Where to see results |
+|--------|------|----------------------|
+| **GitLab** `prof-correctness` job | After `upload all`; profiling path changes on `main` or MR | [prof-correctness Actions](https://github.com/DataDog/prof-correctness/actions/workflows/downstream-python.yml) — filter by commit SHA |
+| **GitHub** `.github/workflows/prof-correctness.yml` in dd-trace-py | Profiling path changes on PR/push; `workflow_dispatch` | Same Actions page |
+
+Both use [dd-octo-sts](https://github.com/DataDog/dd-octo-sts-action) (`dd-trace-py.gitlab.trigger-ci` / `dd-trace-py.github.trigger-ci`) to call `gh workflow run downstream-python.yml`.
+
+**Inputs:**
+
+- `dd_trace_py_commit_sha` — commit to test (required)
+- `test_scenarios` — regexp passed to `TEST_SCENARIOS` (see the [3.14/3.15 migration gate index](scenarios/python_downstream_gate/README.md); the downstream workflow default alone is `python.*`)
+
 ## Creating new tests 
 
 ### Define the dockerfile 

base_images/Dockerfile.python-3.14

@@ -0,0 +1,10 @@
+FROM python:3.14 AS base
+
+ARG DDTRACE_INSTALL_URL=""
+RUN if [ -n "$DDTRACE_INSTALL_URL" ]; then \
+      curl -fsSL "$DDTRACE_INSTALL_URL" | bash; \
+    fi
+
+ENV DD_PROFILING_ENABLED=true
+ENV DD_TRACE_ENABLED=false
+ENV DD_PROFILING_OUTPUT_PPROF="/app/data/profiles"

base_images/Dockerfile.python-3.15

@@ -0,0 +1,10 @@
+FROM python:3.15.0b1 AS base
+
+ARG DDTRACE_INSTALL_URL=""
+RUN if [ -n "$DDTRACE_INSTALL_URL" ]; then \
+      curl -fsSL "$DDTRACE_INSTALL_URL" | bash; \
+    fi
+
+ENV DD_PROFILING_ENABLED=true
+ENV DD_TRACE_ENABLED=false
+ENV DD_PROFILING_OUTPUT_PPROF="/app/data/profiles"

cmd/list-scenarios/main.go

@@ -13,6 +13,7 @@
 // Usage:
 //
 //	go run ./cmd/list-scenarios -pattern 'python.*' -chunk-size 3
+//	go run ./cmd/list-scenarios -pattern 'python.*' -exclude '_3\.15$' -chunk-size 3
 package main
 
 import (
@@ -39,7 +40,7 @@ type matrixEntry struct {
 	Names string `json:"names"`
 }
 
-func run(pattern, scenariosDir string, chunkSize int) ([]matrixEntry, error) {
+func run(pattern, exclude, scenariosDir string, chunkSize int) ([]matrixEntry, error) {
 	// Anchor the user pattern so e.g. "python" doesn't accidentally match
 	// "python_basic_idle_3.12". The non-capturing group preserves precedence of
 	// any alternation inside the user pattern.
@@ -48,21 +49,38 @@ func run(pattern, scenariosDir string, chunkSize int) ([]matrixEntry, error) {
 		return nil, fmt.Errorf("invalid -pattern: %w", err)
 	}
 
+	// Optional exclusion, applied to names that matched -pattern. Unlike
+	// -pattern this is NOT anchored, so a suffix like `_3\.15$` drops every
+	// name ending in that version. Go's regexp is RE2 (no lookahead), so
+	// "match python but not the wheel-only variants" must be expressed as a
+	// separate exclude rather than a negative lookahead in -pattern.
+	var excludeRe *regexp.Regexp
+	if exclude != "" {
+		excludeRe, err = regexp.Compile(exclude)
+		if err != nil {
+			return nil, fmt.Errorf("invalid -exclude: %w", err)
+		}
+	}
+
 	entries, err := os.ReadDir(scenariosDir)
 	if err != nil {
 		return nil, fmt.Errorf("read %s: %w", scenariosDir, err)
 	}
 
 	var names []string
 	for _, e := range entries {
-		if e.IsDir() && re.MatchString(e.Name()) {
-			names = append(names, e.Name())
+		if !e.IsDir() || !re.MatchString(e.Name()) {
+			continue
+		}
+		if excludeRe != nil && excludeRe.MatchString(e.Name()) {
+			continue
 		}
+		names = append(names, e.Name())
 	}
 	sort.Strings(names)
 
 	if len(names) == 0 {
-		return nil, fmt.Errorf("no scenarios matched pattern %q in %s", pattern, scenariosDir)
+		return nil, fmt.Errorf("no scenarios matched pattern %q (exclude %q) in %s", pattern, exclude, scenariosDir)
 	}
 
 	// Pack into chunks of at most chunkSize, preserving sorted order.
@@ -88,6 +106,7 @@ func run(pattern, scenariosDir string, chunkSize int) ([]matrixEntry, error) {
 
 func main() {
 	pattern := flag.String("pattern", "", "regex selecting scenario directory names (anchored as ^pattern$)")
+	exclude := flag.String("exclude", "", "regex dropping matched names (unanchored, RE2); e.g. '_3\\.15$'")
 	scenariosDir := flag.String("scenarios-dir", "scenarios", "path to the scenarios directory")
 	chunkSize := flag.Int("chunk-size", 3, "max scenarios per matrix entry")
 	flag.Parse()
@@ -103,7 +122,7 @@ func main() {
 	}
 
 	abs, _ := filepath.Abs(*scenariosDir)
-	out, err := run(*pattern, *scenariosDir, *chunkSize)
+	out, err := run(*pattern, *exclude, *scenariosDir, *chunkSize)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "error: %v (resolved scenarios dir: %s)\n", err, abs)
 		os.Exit(1)

cmd/list-scenarios/main_test.go

@@ -6,6 +6,7 @@ import (
 	"path/filepath"
 	"reflect"
 	"regexp"
+	"strings"
 	"testing"
 )
 
@@ -37,7 +38,7 @@ func TestRun_ChunksAlphabetically(t *testing.T) {
 		"node_heap", // must be filtered out by the pattern
 	})
 
-	got, err := run("python.*", root, 3)
+	got, err := run("python.*", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -62,7 +63,7 @@ func TestRun_ChunksAlphabetically(t *testing.T) {
 func TestRun_SingleChunkWhenSmall(t *testing.T) {
 	root := mkScenarios(t, []string{"dotnet_wall", "dotnet_alloc"})
 
-	got, err := run("dotnet.*", root, 3)
+	got, err := run("dotnet.*", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -87,7 +88,7 @@ func TestRun_AnchoringRejectsSubstringMatches(t *testing.T) {
 		"python_cpu_sleep_sync_3.12",
 	})
 
-	got, err := run("python_cpu", root, 3)
+	got, err := run("python_cpu", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -101,7 +102,7 @@ func TestRun_ExactChunkSizeBoundary(t *testing.T) {
 	root := mkScenarios(t, []string{
 		"a", "b", "c", "d", "e", "f",
 	})
-	got, err := run(".*", root, 3)
+	got, err := run(".*", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -113,10 +114,46 @@ func TestRun_ExactChunkSizeBoundary(t *testing.T) {
 	}
 }
 
+func TestRun_ExcludeDropsMatchedNames(t *testing.T) {
+	// Mirrors the CI python gate: run everything python except the wheel-only
+	// variants (every *_3.15 plus python_live_heap_3.14).
+	root := mkScenarios(t, []string{
+		"python_cpu",
+		"python_lock_3.14",
+		"python_lock_3.15",
+		"python_mem_domain_3.14",
+		"python_mem_domain_3.15",
+		"python_live_heap_3.14",
+		"python_live_heap_3.15",
+	})
+
+	got, err := run("python.*", `_3\.15$|^python_live_heap_3\.14$`, root, 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var names []string
+	for _, e := range got {
+		names = append(names, e.Names)
+	}
+	joined := strings.Join(names, ", ")
+	want := "python_cpu, python_lock_3.14, python_mem_domain_3.14"
+	if joined != want {
+		t.Fatalf("excluded set wrong:\n got %q\nwant %q", joined, want)
+	}
+}
+
+func TestRun_InvalidExcludeIsError(t *testing.T) {
+	root := mkScenarios(t, []string{"python_cpu"})
+	if _, err := run("python.*", "[invalid", root, 3); err == nil {
+		t.Fatal("expected error on invalid exclude regex")
+	}
+}
+
 func TestRun_NoMatchIsError(t *testing.T) {
 	root := mkScenarios(t, []string{"python_cpu"})
 
-	_, err := run("ruby.*", root, 3)
+	_, err := run("ruby.*", "", root, 3)
 	if err == nil {
 		t.Fatal("expected error when no scenarios match")
 	}
@@ -125,7 +162,7 @@ func TestRun_NoMatchIsError(t *testing.T) {
 func TestRun_InvalidPatternIsError(t *testing.T) {
 	root := mkScenarios(t, []string{"python_cpu"})
 
-	if _, err := run("[invalid", root, 3); err == nil {
+	if _, err := run("[invalid", "", root, 3); err == nil {
 		t.Fatal("expected error on invalid regex")
 	}
 }
@@ -140,7 +177,7 @@ func TestRun_RegexMatchesIntendedDirAndOnlyThat(t *testing.T) {
 		"python_cpu_sleep_sync_3.12",
 		"python_basic_idle_3.12",
 	})
-	got, err := run("python.*", root, 3)
+	got, err := run("python.*", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -175,7 +212,7 @@ func TestRun_RegexMatchesIntendedDirAndOnlyThat(t *testing.T) {
 // verifies it round-trips to the expected shape.
 func TestRun_OutputIsValidJSON(t *testing.T) {
 	root := mkScenarios(t, []string{"a", "b", "c", "d"})
-	got, err := run(".*", root, 3)
+	got, err := run(".*", "", root, 3)
 	if err != nil {
 		t.Fatal(err)
 	}

scenarios/python_downstream_gate/README.md

@@ -0,0 +1,53 @@
+# Python downstream gate (dd-trace-py)
+
+Paired **3.14 (baseline)** and **3.15 (candidate)** prof-correctness scenarios
+exercise the Python profiling stack for the 3.14 → 3.15 migration. They are the
+intended default set when dd-trace-py triggers downstream CI on profiling changes.
+
+**Scenarios land in follow-up PRs** (core families first, then feature-specific
+pairs). This directory is an index only — not a runnable scenario.
+
+## Scenarios
+
+| Family | 3.14 (baseline) | 3.15 (candidate) | PR |
+|--------|-----------------|---------------------|-----|
+| _(pending)_ | — | — | Core scenarios in follow-up PRs |
+
+## Default downstream regexp
+
+Once scenarios are added, dd-trace-py should pass an explicit regexp (not the
+downstream workflow default of `python.*`). The regexp grows as families merge;
+see each PR for the current value.
+
+Override via `workflow_dispatch` → `test_scenarios`, or when triggering
+[`downstream-python.yml`](../../.github/workflows/downstream-python.yml) manually.
+
+## Wheel install
+
+Every scenario builds against a **dd-trace-py wheel** via `DDTRACE_INSTALL_URL`
+(as `downstream-python.yml` does:
+`https://dd-trace-py-builds.s3.amazonaws.com/<sha>/install.sh`), pre-installed in
+the base image.
+
+- **All `*_3.15` folders** — PyPI wheels may not be published for 3.15 yet;
+  excluded from prof-correctness `main` CI (see `test_scenarios_exclude` in
+  [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)).
+- **Wheel-only 3.14 folders** — scenarios that depend on unreleased ddtrace
+  features are also excluded from `main` CI until the feature ships.
+
+## Local run
+
+```sh
+export DDTRACE_INSTALL_URL="https://dd-trace-py-builds.s3.amazonaws.com/<commit-sha>/install.sh"
+TEST_SCENARIOS='<gate-regexp>' go test -v -run TestScenarios
+```
+
+## Gate lifecycle
+
+This gate tests the **migration delta** (3.14 → 3.15). It is time-boxed: retire
+the paired 14v15 framing at 3.15 GA and fold workloads into steady-state
+prof-correctness on {oldest, newest} supported Python versions.
+
+## Further reading
+
+- prof-correctness downstream wiring: [README](../../README.md#downstream-from-dd-trace-py)