refactor: bind the live WanGP instance behind a generation wall

[IAnMove]

PR body — Paso 1 muro WanGP

Rama: refactor/wangp-generation-wall
Commit: 84c9e4d315642e166c38a6bd6c9932608e4723bf
Compare: https://github.com/IAnMove/hocuspocus/compare/main...refactor/wangp-generation-wall?quick_pull=1

El token local de gh (fine-grained PAT) puede hacer push y listar PRs, pero no pull_requests:write ni actions:write. Abrir el PR desde esa URL (o ampliar el PAT) y pegar el cuerpo siguiente.

---

Alcance exacto

Paso 1 del plan canónico: muro WanGP.

• Nuevo app/services/generation/ con bind_wgp() / get_wgp(), más puertos delgados ModelCatalog (get_model_def) y RuntimeConfig (server_config).
• _launch_runtime.py importa WanGP una sola vez tras el parche de argv y enlaza esa instancia viva con bind_wgp(wgp).
• Tras el bind, get_wgp() is sys.modules["wgp"].
• Los 13 accesos HocusPocus restantes (estáticos y dinámicos) salen del allowlist mediante el muro o puertos estrechos.
• Concat de vídeo no entra en el puerto de generación: vive en services.mix_concat.
• No se envuelve _run_generation. No se crea GenerationEngine. No se toca app/models/** ni código vendor WanGP.

Un commit revertible. Sin features nuevas ni cambios de contrato JSON.

Accesos WanGP eliminados

Sitio anterior	Sustitución
_launch_runtime.py rejoin_clips	services.mix_concat.concatenate_multi_clip_videos → get_wgp()
alternative_songs.py remount_clips	mismo puerto de concat
enhance_guides.py get_enhance_guide	ModelCatalog.get_model_def
llm_service.py enhance_prompt	ModelCatalog.get_model_def
director_pipeline.py _run_pipeline	RuntimeConfig.get("vram_safety_coefficient")
director/prompt_polish.py (2)	get_wgp().get_lora_dir
model3d_service.py (3)	RuntimeConfig
shared/api.py importlib.import_module('wgp')	get_wgp() / bind de sys.modules["wgp"]
shared/magic_mask.py (2)	get_wgp() en runtime

Allowlist 1.0: solo ("app/_launch_runtime.py", "<module>", "import wgp").

Tests locales

• python -m pytest -q → 1551 passed
• Gate + bind/get_wgp: 8 passed × 3
• Relacionados generate/enhance/Director/model3d/magic mask/songs: 326 passed
• compileall de módulos tocados, verify_clean_repo, check_documentation_links, check_brand_contract, check_dependency_contract: PASS

Riesgos y rollback

Rollback: git revert 84c9e4d.

Riesgo: WanGPSession deja de ser un segundo bootstrap. Studio/launch no cambia.

No se tocó vendor WanGP. Paridad JSON y arranque conservadas.

No mergear desde el agente. Dueño: humano. Hotspot _launch_runtime.py.

---

Note

Medium Risk
Touches launch bootstrap and every former direct wgp access path; behavior should be equivalent but mis-ordered bind or an unbound get_wgp() call would fail at runtime across generation, media, and config reads.

Overview
Introduces app/services/generation/ as the only supported way for first-party code to reach the live WanGP module after bootstrap: bind_wgp(wgp) runs in _launch_runtime.py right after the single import wgp, and callers use get_wgp(), get_model_def, or RuntimeConfig instead of importing wgp themselves.

Call-site migrations include enhance/LLM model defs, Director LoRA dirs and OOM vram_safety_coefficient, model3d service config, magic mask video/SAM3 helpers, WanGPSession (reuse bound module or bind from sys.modules), and clip rejoin/remount paths that now go through services.mix_concat.concatenate_multi_clip_videos (thin delegate to the bound helper).

Architecture enforcement tightens: the wgp import allowlist shrinks to launch bootstrap only; services/generation must not reimport wgp; a new AST test asserts import wgp → bind_wgp(wgp) order. Docs in ARCHITECTURE_FOUNDATION.md describe the wall. Unit tests cover bind/unbound behavior and the concat port.

^{Reviewed by Cursor Bugbot for commit 84c9e4d. Configure here.}

[github-actions]

PR Review — Loreframe Studio

Risk: low
Scope: 16 file(s); +275/-54; backend services, docs

Automated review from scripts/analyze_pr.py. This is a heuristic pass (no LLM) so humans still own the merge decision.

Findings

• No heuristic issues. Still run the CI checklist below.

Changed files

• added: app/services/generation/__init__.py, app/services/generation/runtime.py, tests/test_generation_runtime.py
• modified: app/_launch_runtime.py, app/services/alternative_songs.py, app/services/director/prompt_polish.py, app/services/director_pipeline.py, app/services/enhance_guides.py, app/services/llm_service.py, app/services/mix_concat.py, app/services/model3d_service.py, app/shared/api.py, app/shared/magic_mask.py, docs/development/ARCHITECTURE_FOUNDATION.md, tests/test_architecture_contracts.py, tests/test_mix_concat.py

CONTRIBUTING checklist

• python scripts/verify_clean_repo.py
• python -m compileall -q app/services app/launch.py scripts
• cd ui && npm run build if the UI changed
• No weights, CivitAI sidecars, or generated guides
• Stays local-first (no required accounts / telemetry)

Posted by the repo PR review workflow. Re-runs on each push to the PR.

[IAnMove]

Codex review

[IAnMove]

cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 84c9e4d. Configure here.}