# Public API — `mgf-test-supervisor`

> The **contract list**. Every public name is re-exported from the package root
> (`from mgf.test_supervisor import …`) and enumerated in each module's `__all__`.
> Machine companion: [`PUBLIC_API.json`](PUBLIC_API.json) (generated by
> `tools/generate_public_api_json.py`, pinned in CI). **Tiers:** `stable` = the
> alignment-pinned schema/tier contract (changes are breaking + cutover-guided);
> `experimental` = 0.x reusable primitives, may change with a deliberate pin-walk.

> **Note:** mgf-test-supervisor is primarily a CLI (`mgf-test-supervisor` / `mtest`).
> This Python surface is for siblings that reuse the schema + selection primitives.


## `mgf.test_supervisor.records`

| Name | Tier | Description |
|---|---|---|
| `JsonlWriter` | stable | Append-only JSONL writer. Best-effort atomic per-line append |
| `OUTCOMES` | stable | frozenset() -> empty frozenset object |
| `SCHEMA_VERSION` | stable | str(object='') -> str |
| `SECTION_HEADER_FMT` | stable | Failure-bundle section-header line format (TS-27); vendored byte-for-byte from `mgf.common.testing` (alignment-pinned) |
| `SECTION_ORDER` | stable | Canonical failure-bundle section order (TS-27); vendored byte-for-byte from `mgf.common.testing` (alignment-pinned) |
| `SEVERITIES` | stable | frozenset() -> empty frozenset object |
| `TestRecord` | stable | One row in the run's JSONL log. Shape mirrors DoctorFinding |
| `now_iso` | stable | Wall-clock ISO-8601 UTC timestamp. Used for record ts_iso |
| `read_jsonl` | stable | Read a JSONL file, tolerating a partial trailing line |
| `severity_for_outcome` | stable | Default severity per outcome. Callers can override (e.g. a |

## `mgf.test_supervisor.tiers`

| Name | Tier | Description |
|---|---|---|
| `DEFAULT_TIER` | stable | int([x]) -> integer |
| `MARKER_TIER` | stable | dict() -> new empty dictionary |
| `TIERS` | stable | Built-in immutable sequence |
| `TierBudget` | experimental | Per-tier wall-clock budget + semantic intent (field names unified with `mgf.common.testing.TierBudget`) |
| `auto_tier` | experimental | Return (effective_tier, reason). Reason is None when the |
| `parse_tier_range` | experimental | Parse a tier spec like `0`, `0-2`, `1-3`, `2` |
| `tier_for_markers` | experimental | The effective tier for a test with these markers (highest-wins; `override` / `mapping` args match `mgf.common.testing.effective_tier`) |

## `mgf.test_supervisor.selection`

| Name | Tier | Description |
|---|---|---|
| `SelectionReport` | experimental | Audit trail for the contributor — every input test is |
| `TestCandidate` | experimental | One test, as seen by the selector. `estimated_duration_s` |
| `build_candidates` | experimental | Wrap raw pytest collection output + state files into |
| `select_tests` | experimental | Filter + budget. Returns a SelectionReport with the final |

## `mgf.test_supervisor.quarantine`

| Name | Tier | Description |
|---|---|---|
| `FAILURES_TO_QUARANTINE` | experimental | int([x]) -> integer |
| `FAILURE_OUTCOMES` | experimental | frozenset() -> empty frozenset object |
| `PASSES_TO_EVICT` | experimental | int([x]) -> integer |
| `PASS_OUTCOMES` | experimental | frozenset() -> empty frozenset object |
| `QuarantineEntry` | experimental | One quarantined test's state |
| `QuarantineStore` | experimental | Persistent quarantine state. Loaded eagerly, saved on each |
| `WINDOW_SIZE` | experimental | int([x]) -> integer |

## `mgf.test_supervisor.perf`

| Name | Tier | Description |
|---|---|---|
| `PerfStore` | experimental | Incremental index of per-test perf artifacts under ``perf_dir`` |
| `aggregate_self_time` | experimental | Sum self-time (tottime) per function across all tests → run hotspots |
| `render_perf_section` | experimental | Render one test's perf record for a TS-27 failure bundle / report |
| `render_run_summary` | experimental | Run-level perf rollup: slowest tests + hottest functions |
| `slowest_tests` | experimental | The ``top`` slowest tests by captured call-phase ``total_ms`` |

## `mgf.test_supervisor.supervisor`

| Name | Tier | Description |
|---|---|---|
| `ChunkResult` | experimental | Outcome of running one chunk of tests |
| `DEFAULT_CHUNK_SIZE` | experimental | int([x]) -> integer |
| `DEFAULT_PER_TEST_TIMEOUT_S` | experimental | Convert a string or number to a floating point number, if possible |
| `RunConfig` | experimental | All knobs for one mtest invocation. Populated by __main__ |
| `SIGTERM_GRACE_S` | experimental | Convert a string or number to a floating point number, if possible |
| `Supervisor` | experimental | The driver. One Supervisor per `mtest` invocation |
| `collect_test_markers` | experimental | Marker map for all collected tests — ONE pytest spawn (derives from `collect_tests`) |
| `collect_tests` | experimental | Collect node-ids AND their markers in ONE pytest spawn |

## `mgf.test_supervisor.diagnostics`

| Name | Tier | Description |
|---|---|---|
| `DAEMON_PROCESS_NAME` | experimental | (see source) |
| `daemon_state` | experimental | Live state of any daemon-process-name matches on this host |
| `dmesg_tail` | experimental | Last N lines of dmesg. May be empty on locked-down hosts |
| `env_fingerprint` | experimental | Project-wide environment fingerprint. Python version, |
| `process_tree` | experimental | `ps -auxf` rooted at `pid`. Useful when a test spawned |
| `recent_history` | experimental | Last N outcomes for `test_id` from the durations store |

## `mgf.test_supervisor.self_check`

| Name | Tier | Description |
|---|---|---|
| `run_self_check` | experimental | Run each canned scenario in isolation. Returns True if all |
