Connector registration discipline (pro mnoho aplikací)¶

Proč: connector registry je SSOT cross-app závislostí (compatibility gate, launcher install-gate, decommission tracking). Když registr neodpovídá realitě, celý modul lže. Tenhle doc je závazný postup, ať registr nedriftuje jak přibývají vendor apps. Vznik: 2026-06-03 (drift ai-chat-async odhalen verifikací app-legal↔ai-helper).

Mechanismus registrace¶

POST /admin/connectors/register (body = connector.json: app_slug, app_version, provides[], consumes[]). Idempotentní per (app_slug, app_version). - Auth: super_admin JWT NEBO localhost bypass (127.0.0.1/::1 → super_admin). → CI/act_runner běží na hostu, takže curl http://127.0.0.1:8000/... projde bez tokenu. To je designovaná auto-register cesta. - Provides: vytvoří connector pokud chybí + INSERT version (skip pokud existuje) + provider dep. Consumes: upsert consumer dep. - Po každém register se spustí recompute_compatibility (advisory).

Dva traps, které způsobují drift¶

Trap 1 — registrace je oddělená od deploye¶

Když appka přidá/změní connector v connector.json, ale nepřeregistruje, registr drží starý stav. Appka se mění, registr hnije. → Fix: auto-register na každém deployi (níže).

Trap 2 — consumer-before-provider TICHÝ skip ⚠️¶

register_app_connectors u consumes: pokud konektor ještě neexistuje (provider ho neregistroval), consume se tiše zahodí (log.warning "declares unknown connector — skip") — app_connector_deps.connector_id je NOT NULL, nelze uložit dep bez connectoru. Nevznikne ani compatibility issue. Takže: - Provider MUSÍ být registrovaný PŘED consumerem. - Jinak consume zmizí beze stopy a recheck ho nedohledá (recheck kouká jen na existující deps).

→ Pravidlo: provider-first. Platform/provider app registruje dřív než její consumeři. (Sharp edge k opravě v connector v0.2: consume neznámého konektoru by měl založit viditelný pending/critical issue, ne tiše spadnout.)

Závazný postup (každá vendor app)¶

connector.json = SSOT. Provides i consumes deklaruj tam, ne ad-hoc.
Auto-register v backend.yml (po úspěšném deployi, krok běží na act_runner = host → localhost bypass):
```
- name: Register connectors (platform registry, provider-first)
  run: |
    curl -sS -X POST http://127.0.0.1:8000/admin/connectors/register \
      -H 'Content-Type: application/json' \
      --data @connector.json
    # non-2xx → ::warning:: (drift se chytí v CI), non-fatal
```
✅ Zabudováno v avax-app-template/.gitea/workflows/backend-deploy.yml.example (provider-first + ::warning:: na ne-2xx + drop prázdných _example entries; scaffold services/gitea.py ho substituuje do backend.yml → nové appky to dostanou zdarma). ⏳ Retrofit existujících: app-ai-helper ✅ (bb7e42f); app-legal / app-hotline / app-kontakty ⏳ (jejich Claude).
Provider-first při novém konektoru: když zavádíš nový shared connector (typicky platform/ai-helper provides), nasaď + zaregistruj providera dřív, pak teprve consumery. Jinak Trap 2.
Po onboardingu ověř: GET /admin/connectors/{name} ukáže provider + versions + deps; POST /admin/connectors/recheck → 0 critical.

Onboarding checklist — přidat¶

Do reference_vendor_app_onboarding / vendor-onboarding fáze „connector": - [ ] connector.json deklaruje provides + consumes (semver / version_range) - [ ] backend.yml má auto-register krok (z template) - [ ] nový shared connector → provider nasazen+registrován dřív než consumer - [ ] recheck po deployi = 0 critical

Stav 2026-06-03 (po opravě ai-chat-async)¶

ai-chat-async 0.1.0 registrován (provider app-ai-helper, rest, public).
app-legal consumer dep ai-chat-async ^0.1.0 active, recheck 0 issues.
⏳ Durabilita (handoff): app-ai-helper connector.json musí deklarovat provides ai-chat-async 0.1.0 (registr bootstrapnut z platform strany — ať connector.json sedí); app-legal connector.json consume přidán lokálně → commitnout; oba doplnit auto-register do backend.yml.

Související¶

docs/spec/connector.md — connector modul spec
backend/app/services/connectors.py — register + recompute_compatibility
docs/spec/core-api-ai-decommission.md — registr = tracking kdo visí na legacy