refactor(models): centralize router Pydantic models in models.py (INV-14, #654)

[AndriiPasternak31]

What

Clears Architectural Invariant #14 (Pydantic models centralized in models.py) for issue #654: moves 97 request/response BaseModel classes out of 32 routers into src/backend/models.py, plus the fan_out / loops / webhooks module-level constants their validators reference. Each class moved verbatim — validators, default_factory, and Config preserved.

#654 was a stale validate-architecture drift report flagging INV-7 / INV-8 / INV-14. Scope (confirmed in plan review): this PR clears INV-14 only (backend, mechanical) + applies the D1/D2 doc fixes. INV-7 (frontend api.js) and INV-8 (auth sprawl) are split into separate child issues — they're owned by other areas and need behavioral/security work.

Why flat models.py (not a models/ package)

A package dir would break two by-file mechanisms invisible to source-only CI (the #1033 class): tests/conftest.py's by-file model preload, and the Dockerfile's by-file COPY *.py. Flat keeps both working. Scope is router models only — db_models.py (95) and adapters/base.py (4) are intentional separate homes.

Behaviour preserved — two proofs

The move is mechanically simple but not purely build-time: a careless cut-paste can change runtime validation while imports + schema still pass. Both gaps are covered:

1. Normalized app.openapi() snapshot diff — origin/dev vs branch: 330 paths / 198 schemas, byte-for-byte identical. Schema-level proof.
2. Validator-preservation unit tests (tests/unit/test_router_model_validators.py) — the @field_validator logic, default_factory dicts, and Config.from_attributes that an OpenAPI diff cannot see, for the 5 behaviour-bearing files (fan_out, loops, canary, audit_log, schedules).

One documented exception (allowlisted in the guard)

canary.py::RunCycleRequest stays in its router: it evaluates INVARIANTS (from the canary library) in a Field(description=…) at class-definition time, and the canary library imports TaskExecutionStatus back from models. Relocating it would force models.py to from canary import …, inverting the dependency direction of a module meant to be a low-level leaf everything imports from. The new static guard allowlists exactly this one model (and fails if the allowlist goes stale).

Tests / docs

• tests/unit/test_models_centralized.py — static guard: no BaseModel under routers/ except the documented allowlist; + planted-violation tests.
• tests/unit/test_router_model_validators.py — 19 validator / default_factory / Config-preservation negatives.
• test_telegram_webhook_backfill.py — its standalone settings.py loader now uses the real models module (a safe leaf) instead of a partial fake, and stubs the services.agent_service.capabilities import (bug: agent creation crashes with opaque ValueError on non-integer CPU in template resources #1197). This test was already red on origin/dev (bug: agent creation crashes with opaque ValueError on non-integer CPU in template resources #1197 standalone-load gap); it is now green.
• docs/memory/architecture.md — Invariant Add internal health route, without which main didn't start #14 scope note + re-measured router/service/agents.py counts.

Verification

• python -c "import main" — clean.
• Full tests/unit suite: only the two pre-existing failure clusters remain (test_1115_schedules_summary, test_login_rate_limit_split — both confirmed failing identically on pristine origin/dev). Zero new failures; +23 passing tests (19 new + 4 telegram fixed).
• ruff: error breakdown byte-identical to origin/dev (zero new lint).
• verify-local is optional here — flat move, no new module dir, no dep/Docker change (models.py is already in the COPY *.py).

🤖 Generated with Claude Code

---

Closes #654 (narrowed to INV-14 + docs). INV-7 → #1309, INV-8 → #1310.

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[vybe]

Validated via /validate-pr — clean refactor (CSO verdict CLEAR, behavior-preserving, dedicated centralization tests, Closes #654). Blocking only on a rebase: this is now CONFLICTING with dev after #1333 and #1317 merged, both of which added new models:

• #1333 — cancelled-status models in routers/agents.py / chat.py / paid.py / public.py + models.py
• #1317 — access models in routers/sharing.py

Please rebase onto current dev and relocate those newly-added models into models.py so INV-14 centralization stays complete. Otherwise good to go.

— posted via /validate-pr

[AndriiPasternak31]

@vybe — rebase done + ready for re-review.

Conflict resolved: merged current dev (5d6cd26). The models added to dev after your review are relocated into models.py, and all conflict-touched routers now have zero inline BaseModel:

• feat(executions): propagate cancelled terminal status end-to-end (#679) #1333 cancelled-status models → BulkCancelRequest etc. in models.py; agents.py/chat.py/paid.py/public.py clean.
• feat(access): Access tab — manage Trinity operators per agent (trinity-enterprise#17) #1317 access models → AccessPolicy/AccessPolicyUpdate/AccessRequest/AccessRequestDecision in models.py; sharing.py imports them.

mergeable = MERGEABLE; full CI green (pytest base+head × 3 seeds, schema-parity, prod-image-smoke, regression-diff, verify-non-root, CodeQL).

Plus one follow-up commit (fa7b617): /sync-feature-flows caught three flow docs still citing a routers/X.py model home this PR emptied — repointed to models.py (citation-only, no behavioral change):

• scheduling.md — ScheduleUpdateRequest → models.py:1574
• audit-trail.md — fixed wrong invariant number (Security: Agent Credential Leakage in Execution Logs [FIXED] #15 → Add internal health route, without which main didn't start #14) and the now-inverted "response models in routers/audit_log.py" claim → models.py:947-982
• business-validation.md — Schedule/execution response models → models.py

Could you re-review to clear the stale CHANGES_REQUESTED?