90 lines
2.6 KiB
Markdown
90 lines
2.6 KiB
Markdown
|
# Phase 278 P0: Remove deprecated PHI debug env vars
|
||
|
|
|
||
|
|
Status: planned / cleanup
|
||
|
|
|
||
|
|
Goal: remove legacy PHI-related environment variables that were consolidated in Phase 277 P2, so the ecosystem converges to a single set of PHI debug knobs.
|
||
|
|
|
||
|
|
SSOT references:
|
||
|
|
- Consolidation completion: `docs/development/current/main/phases/phase-277/P2-COMPLETION.md`
|
||
|
|
- Env var reference (current): `docs/reference/environment-variables.md`
|
||
|
|
|
||
|
|
Target SSOT (post-Phase 278):
|
||
|
|
- `NYASH_LLVM_DEBUG_PHI=1`
|
||
|
|
- `NYASH_LLVM_DEBUG_PHI_TRACE=1`
|
||
|
|
- `NYASH_LLVM_PHI_STRICT=1`
|
||
|
|
|
||
|
|
Non-goals:
|
||
|
|
- introduce new debug toggles
|
||
|
|
- change PHI behavior (only remove deprecated inputs)
|
||
|
|
- change CLI defaults
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1) Identify deprecated env vars (remove inputs)
|
||
|
|
|
||
|
|
Remove support for the legacy variables that were “merged” in Phase 277 P2.
|
||
|
|
|
||
|
|
Expected deprecated set (verify in `docs/reference/environment-variables.md`):
|
||
|
|
- `NYASH_LLVM_PHI_DEBUG`
|
||
|
|
- `NYASH_PHI_TYPE_DEBUG`
|
||
|
|
- `NYASH_PHI_ORDERING_DEBUG`
|
||
|
|
- `NYASH_LLVM_TRACE_PHI`
|
||
|
|
- `NYASH_LLVM_VMAP_TRACE`
|
||
|
|
- `NYASH_PYVM_DEBUG_PHI` (if still present in code; PyVM line is historical)
|
||
|
|
|
||
|
|
Policy:
|
||
|
|
- Do not keep “silent compatibility”.
|
||
|
|
- If a deprecated var is detected, print a one-line error with the replacement and exit non-zero.
|
||
|
|
|
||
|
|
Rationale:
|
||
|
|
- Keeping deprecated behavior is how env var sprawl comes back.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2) Update the runtime checks to accept only the SSOT set
|
||
|
|
|
||
|
|
Target:
|
||
|
|
- `src/llvm_py/phi_wiring/debug_helper.py` (SSOT entry for PHI debug flags)
|
||
|
|
|
||
|
|
Acceptance:
|
||
|
|
- only the SSOT variables are read
|
||
|
|
- deprecated variables trigger a clear failure message (replacement shown)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3) Update documentation (SSOT)
|
||
|
|
|
||
|
|
Update:
|
||
|
|
- `docs/reference/environment-variables.md`
|
||
|
|
|
||
|
|
Requirements:
|
||
|
|
- Remove deprecated entries from tables (or move them to a “Removed in Phase 278” section).
|
||
|
|
- Keep examples only with `NYASH_LLVM_DEBUG_PHI`, `NYASH_LLVM_DEBUG_PHI_TRACE`, `NYASH_LLVM_PHI_STRICT`.
|
||
|
|
- Add a short migration note:
|
||
|
|
- “If you used X, replace with Y.”
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4) Add/Update smoke coverage
|
||
|
|
|
||
|
|
Minimum:
|
||
|
|
- One LLVM harness smoke that runs with:
|
||
|
|
- `NYASH_LLVM_DEBUG_PHI=1`
|
||
|
|
- `NYASH_LLVM_DEBUG_PHI_TRACE=1`
|
||
|
|
- `NYASH_LLVM_PHI_STRICT=1`
|
||
|
|
and verifies the run completes (no strict-mode violations in the fixture).
|
||
|
|
|
||
|
|
Deprecation enforcement:
|
||
|
|
- One smoke (or a small shell snippet in an existing test) that sets a deprecated var and expects a non-zero exit.
|
||
|
|
|
||
|
|
No new env vars.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5) Completion criteria
|
||
|
|
|
||
|
|
- Deprecated env vars no longer affect behavior (removed from code paths).
|
||
|
|
- Deprecated env vars cause a fail-fast error with a replacement hint.
|
||
|
|
- Docs reflect only the SSOT set.
|
||
|
|
- The representative smokes remain green.
|