AGENTS.md@infrastructure/core/testing git:20261030.82f81c4A

Immutable. This exact content never changes and is served at /api/v1/blob/9e0d68e6a292772a.

# infrastructure/core/testing — agent contract

Test-execution machinery for the template: the per-project pytest runner,
profiles/markers, receipts, coverage probes, and the advisory test-impact
planner. Re-homed from the flat `infrastructure/core/` top level by
`CORE-TESTING-REHOME-1`.

## Invariants

1. Callers import `infrastructure.core.testing.<module>` directly.
2. Private names are package-internal; public helpers belong to their owning
   testing module.
3. General core utilities (`determinism.py`, `script_discovery.py`,
   `runtime/`, `logging/`, …) stay at the core top level — membership here
   means "test-execution machinery", not "used by tests".

## Public surface

See `README.md` for the module table. Key entry points:
`run_per_project_pytest`, `build_union_pytest_command`, `resolve_test_profile`,
`write_public_matrix_receipt`, `run_project_test_matrix`, `output_tree_digest`,
`declared_output_relpaths`, `classify_changed_paths`, `check_cov_datafile_support`.

## Cross-refs

- `infrastructure/core/AGENTS.md` — the parent core contract.
- `tests/infra_tests/core/` — the suite exercising this package.
- Root `TO-DO.md` row `CORE-TESTING-REHOME-1` (closed by this re-home).

## Release acceptance modules

| Module | Role |
| --- | --- |
| `project_test_runtime.py` | Admission of an already prepared project test interpreter; never a resolver. |
| `local_gate.py` | One offline local entry point over the hosted commands, with `--changed`, `--list` and per-stage plans. |
| `ci_module_durations.py` | Measured hosted module seconds from `infrastructure/config/ci-module-durations.json`, the shard load weights they drive, the byte-size fallback for unmeasured modules, and the `pytest-xdist` worker budget `ci_contracts.contract_preparation` derives from them. |

Default functional CI uses `ci_smoke.py` and the explicit `.github/project-smoke.json` selections. Full matrices and coverage union remain available in the manual hardening workflow.

`ci_execution_user.py` is an explicit hosted Linux setup/launch/transport
boundary. Keep privilege confined to scoped preparation; payloads use a fresh
unprivileged account, explicit runtime inputs and the unchanged global census.
Preserve shared cache inodes, source bytes/modes, original exits and failed
evidence. Transport cannot grant runtime or release acceptance. Changes require
independent review and genuine affected hosted execution.

Public Root and project runtime workers create private fixture scratch outside
Source, ancestor Git checkouts and the selected runtime. Only the actual worker
adds that fresh path to its pytest call. Receipt, XML and coverage paths retain
their declared evidence locations and all original deadlines. Scratch cleanup
requires the same held physical directory; transported paths grant no cleanup.