SpeakTrue

Legacy Runtime Compatibility Removal Inventory

Checkpoint: legacy compatibility cleanup-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 legacy adapter cleanup: this legacy compatibility cleanup 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 legacy adapter cleanup 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, media, and coverage artifacts:

Class	Count	Meaning
deploy	6	Procfile/Docker 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 web runtime cleanup-legacy runtime retirement 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/Dockerfile	copies wsgi.py only	deploy migrated	keep gb_tts_app.py out of the production image	Low.	current
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	hard-deprecated import stub	retired legacy entrypoint	delete after one deploy/test cycle proves no external references still need the file path	Medium: accidental imports now fail closed.	current
web/python-web-app/src/app.py	uses legacy_runtime_state_service.get_legacy_runtime_state() and page_bootstrap_service.register_legacy_blueprints	app startup migrated	keep src.app.create_app() as the current app factory while compatibility namespaces are retired	Medium: startup no longer imports gb_tts_app.py or legacy_runtime_adapter; verified by S04/legacy adapter cleanup smoke.	S04/legacy adapter cleanup complete
web/python-web-app/src/jobs/job_store.py	uses persistent_job_service with process runtime state	production helper migrated	keep direct focused-service dependency	Low; direct legacy runtime/adapter imports removed.	S03/legacy adapter cleanup complete
web/python-web-app/src/routes/categories.py	uses category_route_dependencies	route migrated	retire only the transitional monkeypatch surface when tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup complete
web/python-web-app/src/routes/legacy.py	uses legacy_route_dependencies	route migrated with broad compatibility bridge	split remaining compatibility reads only when root/auth/drafts/cache/default-model/pronunciation/Soundboard proof bundles are ready	High; route no longer imports the adapter but still intentionally exposes historical behavior.	legacy adapter cleanup complete
web/python-web-app/src/routes/settings.py	uses settings_route_dependencies	route migrated	retire only the transitional monkeypatch surface when tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup complete
web/python-web-app/src/routes/soundboard.py	uses soundboard_route_dependencies	route migrated	retire only the transitional monkeypatch surface when Soundboard tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup complete
web/python-web-app/src/routes/stt.py	uses speech_route_dependencies	route migrated	retire only the transitional monkeypatch surface when speech tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup complete
web/python-web-app/src/routes/tts.py	uses speech_route_dependencies	route migrated	retire only the transitional monkeypatch surface when speech tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup complete
web/python-web-app/src/routes/voice_clone.py	uses voice_clone_route_dependencies	route migrated	retire only the transitional monkeypatch surface when tests move to focused seams	Medium; route no longer imports the adapter.	legacy adapter cleanup 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 previously imported or monkeypatched gb_tts_app / legacy_runtime heavily. Current tests should avoid gb_tts_app and use src.app.create_app() for app construction or src.legacy_runtime only as the transitional monkeypatch surface. 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 small compatibility test proving gb_tts_app fails closed and legacy_runtime remains transitional 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 now uses src.app.create_app(); remaining monkeypatch-heavy tests should move from src.legacy_runtime to focused service seams in later slices.

Proposed Allowlist by Slice

S02 allowlist/status

Completed in S02:

• Procfile now uses gunicorn 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 used to remain as compatibility import surface; it is now hard-deprecated.
• 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 legacy adapter cleanup seam-deletion status has moved production route/job access to focused dependency providers.
• scripts/verify_legacy_import_isolation.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 remains until the compatibility surface is retired; gb_tts_app.py is hard-deprecated.
• Test files may still import or monkeypatch src.legacy_runtime while later slices remove that compatibility surface.

S04 allowlist/status

Completed in S04:

• src.app.create_app() no longer imports gb_tts_app.py.
• gb_tts_app.py is hard-deprecated, not the deployment entrypoint.
• scripts/verify_legacy_compatibility_boundary.py now guards the legacy compatibility cleanup 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, and JS runtime checks passed.

Final legacy compatibility cleanup/legacy adapter cleanup state:

• No deploy command targets gb_tts_app:app.
• src.app.create_app() gets the bootstrap-owned app from legacy_runtime_state_service and registers blueprints through page_bootstrap_service without importing gb_tts_app.py or legacy_runtime_adapter.
• Route/job files no longer import src.legacy_runtime or src.services.legacy_runtime_adapter directly.
• src/services/legacy_runtime_adapter.py and src/legacy_runtime.py remain as temporary compatibility namespaces for monkeypatch-heavy tests, not as production route dependencies. gb_tts_app.py is a fail-closed deprecation stub.

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-legacy compatibility cleanup 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 emits a hard deprecation error and can be deleted after a deploy/test cycle confirms no external imports still depend on the file path.
• 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_legacy_runtime_retirement.py
python3 scripts/verify_legacy_import_isolation.py
python3 scripts/verify_legacy_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