[PHASE IV] docs(proposals): environment contract and result validity for examples

[vjuhhii]

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds a Phase 4 proposal to docs/proposals/scenarios/example-restoration/, following the phase
folder convention that directory establishes, and updates its index README as the "Notes for
Maintainers" section there requires.

On timing, since it differs from previous phases. #375 and #541 were submitted by mentees after
selection. I am submitting this as an applicant, before selection, so I want to be explicit about
what it is: a proposed direction for Phase 4, grounded in work already in the tree, offered
regardless of who ends up doing it. If maintainers would rather this waited until the phase's mentee
is confirmed, or would rather it were merged and reassigned, both are fine by me — say the word and
I will adjust or close it.

The argument

Phases 1 to 3 progressively answered does this example run? Phase 3 in particular built the
inventory, the tiered validation, the PR-impact classification, and published example health. That
machinery works.

The gap this proposal addresses is that running successfully and measuring meaningfully are
different properties, and only the first is currently verified.

#888 documents the proven case: below compute capability 8.0 PyTorch emulates bfloat16 instead of
refusing it, two LLM examples select it unconditionally on any CUDA device, and on a GTX 1080 that
path measures 1.85× slower than float32. Nothing raises. The benchmark completes and publishes the
number.

What I found while writing this

Phase 3 already reserves Failed: Hardware assumption as a failure cause and publishes
Requires GPU or special hardware as a status. The vocabulary is there. The detection behind it is
_check_cuda_only_assumptions() in static_validator.py:474, a textual scan that exempts any file
containing torch.cuda.is_available().

I ran that check's own regex and exemption rule against the sites in #888:

File	Regex matches	Exempted	Selects bfloat16	Result
eagle_llm.py	yes	no	yes	WARNING, does not block
block/drafter.py	no	—	yes	not seen
block/verifier.py	no	—	yes	not seen
huggingface_llm.py	yes	yes	no	skipped

device == "cuda" is a comparison, not an assignment, so the pattern does not match it. Two of the
three files responsible for the failure mode are invisible to the check designed to find hardware
assumptions, and the exemption rule is precisely the predicate #888 shows to be insufficient.

This is not a criticism of Phase 3. A textual scan is the right first approximation when there is
nothing to check against. The proposal's argument is that there should be something to check
against.

The proposal in one line

An example declares the environment it requires, core resolves what the machine provides,
the run is verified before it produces numbers, and the report records what actually
executed.

A contract evaluates to satisfied, substituted, or unsatisfiable. The distinction between the last
two is the design's centre: refusing every mismatch would make Ianvs unusable on ordinary hardware,
which contradicts the point of an edge-AI benchmark, while publishing a substituted result as native
is the bug. Recording the substitution keeps both properties.

Relationship to work already open

The first two stages are partly implemented, in work done while preparing this: #957 adds
device_profile() and supports_bf16(), an optional min_compute_capability in testenv.yaml,
verification in TestEnv.prepare(), and a fallback warning. #767 and #890 cover the use_gpu
ordering defect and its regression tests.

The proposal also references adjacent work by others — #535 / #536 on local device detection, #845
on a pytest suite for core/, and the get_device() suggestion raised in review of #767 — with the
intent of consuming rather than duplicating it. Where scope overlaps something a contributor has
already begun, I would rather coordinate in those threads.

Contents

• phase-4-2026-term-3/proposal.md — background, problem statement with the verification above,
  proposal, scope, target users, design details with a worked example, functional requirements,
  a roadmap over the Sep 7 – Nov 27 term with a midterm deliverable, acceptance criteria, and risk
  analysis.
• README.md — new row in the phases table and a Phase 4 section, per the maintainer notes in that
  file.

Which issue(s) this PR fixes:

None directly; this is a proposal. Related: #230, #888, #957, #767, #890.

[kubeedge-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: vjuhhii
To complete the pull request process, please assign jaypume after the PR has been reviewed.
You can assign the PR to them by writing /assign @jaypume in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment