Minimizing Ty Ecosystem Changes

Minimizing Ty Ecosystem Changes

Invariants

1. Use the exact Ruff revisions, user-level PR config, dependency cutoff, mypy-primer revision, project Python version, checker environment and deadline, effective target platform, and strictness settings from the Actions run. Match its execution platform when dependency installation or runtime behavior depends on it.
2. Reproduce the reported project difference before explaining it or writing a smaller example.
3. Treat copied binaries and config as read-only, and verify every reduction against both binaries.
4. Derive every candidate from the preceding verified candidate; NEVER substitute an independently constructed example.
5. Preserve the underlying trigger, not merely the diagnostic rule, message, or displayed type.

Start each investigation from fresh artifacts. Do not trust retained memories, previous minimizations, current upstream project state, or the helper script's default lockfile.

Prefix every direct or indirect gh invocation with GH_TELEMETRY=false; each Codex tool call may start a new shell.

Collect Exact-Run Metadata

If the primary agent supplied an immutable TY_ECOSYSTEM_RUN_METADATA manifest, verify that its run ID and attempt match the frozen report and that it contains each assigned project and the reviewed runtime settings described below. All subagents reuse the same read-only manifest; ask the primary agent to supply missing information rather than modifying it or generating another shared manifest.

Otherwise, run the bundled helper once with the Actions run ID or URL, matching attempt, and every affected mypy-primer project name:

export TY_ECOSYSTEM_RUN_METADATA="$PWD/target/ty-ecosystem-run.json"
GH_TELEMETRY=false uv run --script scripts/collect_ty_ecosystem_run_metadata.py \
  <actions-run> <project-name>... \
  --attempt <actions-attempt> \
  --output "$TY_ECOSYSTEM_RUN_METADATA"

The helper collects the analyzed Ruff revisions, Actions EXCLUDE_NEWER, ecosystem-analyzer and mypy-primer revisions, each project's CI Python version, and the original ecosystem config as ty_config. With --output, it also saves analysis-job logs and structured job metadata in an adjacent <output filename>.evidence directory; analysis_jobs records their paths and source URLs. Stop if the helper cannot determine a unique core value; never substitute a comment timestamp or local default.

The current workflow splits compilation into Build ty (base) and Build ty (pr). The helper reads the base job, which records both the merge base and PR merge revision, and still supports historical runs with a single Build ty job.

Checker Environment and Platforms

The helper preserves runtime evidence but does not interpret it. Before publishing the manifest as immutable, the primary agent must inspect the saved analysis-job logs and runner metadata, consulting the selected workflow revision when needed. Determine the environment of the actual analysis command, including any shell overrides, rather than copying settings from an earlier setup step. Read the installed uv version, runner OS and architecture, and effective analyzer profile from the available evidence, checking the default when no profile is specified; a tool-cache hit need not have a download message. Compare the relevant shards and resolve any conflicting or missing information without guessing from the local machine.

Record the verified findings in a runtime object in the manifest: runner_os, runner_arch, default_python_platform, uv_version, analyzer_profile, and checker_env. Include TY_UV, UV_LOCKED, and RUST_BACKTRACE in checker_env, using strings for values and null only when the setting is determined to be unset. A missing or unfamiliar log line is not proof that a variable was unset. Add brief evidence notes identifying the job and log section or workflow setting supporting the findings, then freeze the completed manifest for all workers.

Use the reproduction runner below to restore runtime.checker_env for each binary, including unsetting variables whose recorded value is null, and use the recorded uv version. Ensure any UV executable override selects that version too. For runs that enable PEP 723 script environments with TY_UV=scripts, omitting that value disables script dependency discovery.

Set UV_NO_BUILD=1 and UV_NO_BINARY=0 for script preparation and checker runs, matching ecosystem-analyzer's current overrides. These prevent source-distribution builds while allowing binary distributions. Apply them in addition to the recorded Actions environment, as shown below.

The current analyzer uses a 30-second checker deadline with --profile profiling or --profile release, and 180 seconds otherwise; its default profile is dev. Script preparation has a 180-second deadline. The analyzer profile is independent of the binary's build profile, so prebuilt profiling binaries still receive the default 180-second deadline unless the invocation selects another profile. Preserve these deadlines during reproduction and minimization, and classify expiration separately from an ordinary exit code. Verify the settings when investigating a historical run whose analyzer behavior differs from these current defaults.

Install the copied ecosystem config as user-level configuration so project settings and original command-line arguments retain their precedence. Fill a missing environment.python-platform in that copy with the verified CI default before publishing it, as described below. For example, a Linux default must not override a project's explicit win32 or all setting. When moving a minimized example outside its original project configuration, preserve that project's effective target platform as well.

Choose the execution environment before building binaries or installing dependencies. A ty target-platform option affects type analysis; it does not make uv resolve Linux dependency markers, install Linux wheels, or run Linux build steps on macOS. When platform-dependent dependencies, native extensions, installation commands, or PEP 723 script environments affect the result, run project setup and both compatible ty binaries in an environment matching the selected runner's OS and architecture, such as a container or remote host. Create its virtualenvs there instead of copying virtualenvs from another platform. Local native binaries are suitable when these differences do not affect the reproduction; still preserve the effective checker target and verify the reported difference exactly. Report an unavailable matching environment as a reproduction limitation rather than claiming equivalence.

Prepare ty

If a primary agent supplied freshly copied base and PR profiling binaries plus the PR ecosystem config, preserve their absolute paths as TY_ECOSYSTEM_BASE_BINARY and TY_ECOSYSTEM_PR_BINARY, verify they exist, and reuse them. Do not rebuild those binaries, switch shared Ruff refs, or overwrite the shared artifacts. If an exact-revision debug binary is needed to identify an ambiguous internal type, request it from the primary agent; the profiling binaries remain the behavioral oracle.

Otherwise, require a clean working tree, remember its original ref, and build both exact revisions before assigning any subagent work. Reuse the checkout's existing Cargo target directory, copy the profiling binaries and PR ecosystem config to target/ty-ecosystem-bins, and restore the original ref when finished:

Fetch the PR revision explicitly because pull-request runs usually use a synthetic GitHub merge commit that a normal clone does not contain:

set -euo pipefail

test -z "$(git status --short)" || { git status --short; exit 1; }
original_ref="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
GH_TELEMETRY=false git fetch https://github.com/astral-sh/ruff.git <pr-revision>
mkdir -p target/ty-ecosystem-bins
trap 'git checkout "$original_ref"' EXIT

artifact_dir="$PWD/target/ty-ecosystem-bins"
build_target_dir="${CARGO_TARGET_DIR:-target}"
export CARGO_PROFILE_PROFILING_DEBUG=line-tables-only
jq -er '.ty_config' "$TY_ECOSYSTEM_RUN_METADATA" > "$artifact_dir/ty-ecosystem.toml"

git checkout --detach <merge-base>
cargo build --package ty --profile profiling
cp "$build_target_dir/profiling/ty" "$artifact_dir/ty-base"

git checkout --detach <pr-revision>
cargo build --package ty --profile profiling
cp "$build_target_dir/profiling/ty" "$artifact_dir/ty-pr"

After restoring the original ref, inspect vendored definitions and Rust implementations with git -C <ruff-checkout> show <exact-revision>:<repository-relative-path>, selecting the merge-base or PR revision from the immutable manifest. Never assume working-tree files match either analyzed binary or switch the shared checkout's ref.

Before using or publishing the copied target/ty-ecosystem-bins/ty-ecosystem.toml, inspect its [environment] settings. If python-platform is absent, add it with the verified runtime.default_python_platform value, creating the table if needed. Preserve an existing platform setting and all other options. Make this edit only to the reproduction copy; workers reuse the primary agent's prepared config without modifying it.