SpeakTrue

Legacy Runtime Compatibility Removal Inventory

Milestone: M011-vd50cq
Generated: 2026-05-01
Purpose: Track the remaining legacy_runtime.py / gb_tts_app.py compatibility dependencies before final removal.

Summary

Current status after M013: this M011 inventory is historical for the first compatibility-removal boundary. The newer seam-deletion status is in docs/ops/legacy-runtime-seam-deletion.md. As of the current M013 seam-deletion pass, app startup, job storage, TTS, STT, voice-clone, settings, categories, Soundboard, and legacy compatibility routes no longer import legacy_runtime_adapter; the adapter remains only as a transitional service module with no production route imports.

Static inventory command:

git ls-files | python3 <inventory script matching legacy_runtime|gb_tts_app|wsgi:app|gunicorn>

Current tracked-reference counts, excluding virtualenvs, pycache, graphify caches, media, and coverage artifacts:

Class	Count	Meaning
deploy	7	Procfile/Docker/Vultr entrypoint references.
docs	32	Historical README / implementation-plan references. Not runtime blockers.
production-py	105	Python runtime references or compatibility docstrings/comments. These are the core blocker group.
test	989	Test monkeypatch/import references. Large but expected after M005-M007 wrapper delegation tests.
other	1	Dependency declaration (gunicorn). Not a blocker.

Production and Deploy References

Caller	Current dependency	Classification	Replacement target	Risk	Slice
web/python-web-app/Procfile	gunicorn wsgi:app	deploy migrated	keep wsgi:app	Medium: changed import timing/deploy module; verified by S02 smoke.	S02 complete
web/python-web-app/deploy/vultr/gunicorn.service.example	wsgi:app	deploy example migrated	keep wsgi:app	Low: documentation/config example; aligned in S02.	S02 complete
web/python-web-app/Dockerfile	copies wsgi.py gb_tts_app.py	deploy compatibility	keep until gb_tts_app.py removed, then drop	Low.	S04
web/python-web-app/docker-entrypoint.sh	already uses wsgi:app	deploy aligned	keep	Low.	S02 validate
web/python-web-app/gb_tts_app.py	documented compatibility alias importing/replacing module with src.legacy_runtime	legacy import shim only	keep temporarily; remove after live deploy cycle proves no external imports	High: public import surface for tests/legacy deployments.	S04 complete
web/python-web-app/src/app.py	imports legacy_runtime_adapter for Flask app object and registers blueprints	app startup aligned with compatibility boundary	eventually construct app from explicit bootstrap service with no legacy runtime namespace	Medium: startup no longer imports gb_tts_app.py; verified by S04 smoke.	S04 complete
web/python-web-app/src/jobs/job_store.py	imports legacy_runtime_adapter for job CRUD wrappers	adapter-isolated production helper	direct src.services.persistent_job_service dependency	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/categories.py	imports legacy_runtime_adapter locally for endpoint dependencies	adapter-isolated route blocker	category_runtime_service / route dependency object	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/legacy.py	imports legacy_runtime_adapter locally for endpoint dependencies	adapter-isolated route blocker	split to focused services per endpoint group	High; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/settings.py	imports legacy_runtime_adapter locally for endpoint dependencies	adapter-isolated route blocker	user_settings_service, settings_service, auth/bootstrap helpers	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/soundboard.py	imports legacy_runtime_adapter locally for endpoint dependencies	adapter-isolated route blocker	soundboard_route_service, regeneration_route_service, combined_route_service	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/stt.py	imports legacy_runtime_adapter for STT wrappers	adapter-isolated route blocker	stt_service / speech_runtime_service dependency object	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/tts.py	imports legacy_runtime_adapter for TTS wrappers	adapter-isolated route blocker	tts_service / speech services	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/routes/voice_clone.py	imports legacy_runtime_adapter for voice clone wrappers	adapter-isolated route blocker	voice_clone_service + auth helpers	Medium; direct legacy_runtime.py import removed in S03.	S03 complete
web/python-web-app/src/legacy_runtime.py	self/docstring references and bootstrap service import	target module	deprecation shim or delete	High: only safe after callers move.	S04
src/services/* docstrings mentioning legacy runtime	commentary only	non-blocking	update later if confusing	Low.	S04 optional
src/config.py comments mentioning legacy runtime	commentary only	non-blocking	update after ownership move	Low.	S04 optional

Test Reference Strategy

Tests currently import or monkeypatch gb_tts_app / legacy_runtime heavily. This is expected because M005-M007 intentionally preserved compatibility aliases while extracting behavior. For compatibility removal:

1. Do not bulk-edit tests first. Move runtime code first and keep tests green.
2. For route behavior tests, patch focused service seams once the route imports are migrated.
3. Keep a smaller compatibility test set proving gb_tts_app / legacy_runtime deprecation behavior during one deploy cycle.
4. Delete legacy wrapper delegation tests only when the wrapper itself is deleted or replaced by a hard error shim.

High-volume test blocker groups:

• tests/api/test_soundboard_supabase_mode.py — strict Soundboard monkeypatches; migrate after route dependencies move.
• tests/api/test_voice_clone.py / test_user_settings.py / settings tests — route-level monkeypatches.
• tests/unit/test_legacy_runtime_* — should be retired or replaced by focused service tests in S04.
• tests/conftest.py — currently imports gb_tts_app; should move to src.app.create_app() after S02.

Proposed Allowlist by Slice

S02 allowlist/status

Completed in S02:

• Procfile now uses gunicorn wsgi:app.
• Vultr gunicorn example now uses wsgi:app.
• Docker entrypoint already used wsgi:app and remains aligned.
• WSGI root/health smoke passed.
• Browser auth bootstrap tests passed.

Still allowed after S02:

• gb_tts_app.py remains as compatibility import surface.
• src.app.py may temporarily import gb_tts_app until app factory construction is separated.
• Tests may continue importing gb_tts_app.

S03 allowlist/status

Completed in S03:

• src/jobs/job_store.py no longer imports src.legacy_runtime directly.
• src/routes/** no longer import src.legacy_runtime directly.
• Historical S03 note: remaining route/job compatibility access went through src.services.legacy_runtime_adapter at that point. Current M013 seam-deletion status has moved production route/job access to focused dependency providers.
• scripts/verify_m011_s03_legacy_imports.py fails on new direct route/job imports of legacy_runtime.py.
• Focused route/API/browser-auth/JS regression bundle passed.

Still allowed after S03:

• src/services/legacy_runtime_adapter.py directly imports src.legacy_runtime as the single explicit compatibility boundary.
• src/legacy_runtime.py and gb_tts_app.py remain until S04.
• Test files may still import or monkeypatch legacy compatibility aliases while S04 decides shim vs deletion.

S04 allowlist/status

Completed in S04:

• src.app.create_app() no longer imports gb_tts_app.py.
• gb_tts_app.py is documented as a legacy compatibility alias, not the deployment entrypoint.
• scripts/verify_m011_s04_compatibility_boundary.py now guards the M011 final boundary:
  • deploy entry files target wsgi:app, not gb_tts_app:app;
  • src.app.py does not import gb_tts_app;
  • direct legacy_runtime.py imports are limited to explicit shim surfaces;
  • S03 route/job import isolation remains enforced.
• WSGI smoke, focused API/route regression bundle, JS runtime checks, and graphify rebuild passed.

Final M011 state:

• No deploy command targets gb_tts_app:app.
• src.app.create_app() uses legacy_runtime_adapter.app and registers blueprints without importing gb_tts_app.py.
• Route/job files no longer import src.legacy_runtime directly.
• src/services/legacy_runtime_adapter.py, src/legacy_runtime.py, and gb_tts_app.py remain as the explicit temporary compatibility boundary.

Shim/delete decision:

Full deletion of legacy_runtime.py is deferred until one live wsgi:app deploy cycle proves there are no external imports or runtime-only behavior paths depending on the historical module namespace. Deleting it now would force a broad endpoint dependency rewrite and invalidate the compatibility safety net that keeps monkeypatch-heavy tests and older imports stable.

Post-M011 deletion target

Future deletion work after live deploy proof should target:

• Route modules now import focused dependency providers rather than legacy_runtime_adapter.
• src/services/legacy_runtime_adapter.py can be deleted in a dedicated cleanup once remaining references to the module path itself are removed.
• gb_tts_app.py either imports wsgi.app for compatibility or emits a hard deprecation error.
• legacy_runtime.py is either deleted or reduced to a minimal deprecation shim with no app/runtime state.
• Tests patch focused services except a deliberately small deprecation/compatibility test file.

Verification Hooks

Minimum per-slice hooks:

python3 scripts/verify_m007_s04_runtime_retirement.py
python3 scripts/verify_m011_s03_legacy_imports.py
python3 scripts/verify_m011_s04_compatibility_boundary.py
PYTHONPATH=web/python-web-app web/python-web-app/venv/bin/python - <<'PY'
from src.app import create_app
app = create_app()
client = app.test_client()
assert client.get('/health').status_code == 200
root = client.get('/')
assert root.status_code == 200
print('wsgi smoke OK')
PY
web/python-web-app/venv/bin/pytest web/python-web-app/tests/test_browser_auth_bootstrap.py -q

Final hooks should also include:

web/python-web-app/venv/bin/pytest \
  web/python-web-app/tests/api/test_soundboard_supabase_mode.py \
  web/python-web-app/tests/api/test_tts_soundboard_workflow_target.py \
  web/python-web-app/tests/api/test_speech_contract_hardening.py \
  web/python-web-app/tests/api/test_regeneration_endpoints.py \
  web/python-web-app/tests/api/test_combined_endpoints.py \
  web/python-web-app/tests/api/test_cache_endpoints.py \
  web/python-web-app/tests/api/test_categories.py \
  web/python-web-app/tests/api/test_pronunciations.py \
  web/python-web-app/tests/test_drafts_routes.py \
  web/python-web-app/tests/test_soundboard_routes.py \
  web/python-web-app/tests/test_soundboard_main_tab_surface.py \
  web/python-web-app/tests/test_soundboard_order_update.py -q
node web/python-web-app/tests/js/tts_soundboard_workflow_runtime_check.mjs
node web/python-web-app/tests/js/regeneration_panel_runtime_check.mjs
node web/python-web-app/tests/js/soundboard_category_surface_runtime_check.mjs