ADR-0012 — Le moteur passe à l'AI SDK 7

Statut

Proposé · 2026-09-27

Remplace ou amende : Rien. Précise la ligne IA de la pile : le moteur était sur la v6.

Origine : ADR 0002 du dépôt applicatif Orbit, renumérotée 0012 à l’intégration dans cette série (une seule série d’ADR vit désormais ici).

Statut dans Orbit (2026-10) : en vigueur. Décision reprise de l'ancien dépôt Studio ; le moteur cité est packages/engine (@orbit/engine) de ce dépôt.

Répond au constat G2-19 de l'audit de la phase 3 (« Décider l'AI SDK 7 »). Sources lues le 2026-09-27 : le guide de migration v7 (ai-sdk.dev/docs/migration-guides/migration-guide-7-0), la référence experimental_generateVideo, la documentation vidéo, attribution et rapports de l'AI Gateway (vercel.com/docs/ai-gateway), et les types installés de ai@7.0.116 et @ai-sdk/gateway@4.0.94.

Contexte

Le moteur (packages/engine) est le seul paquet du dépôt qui importe l'AI SDK, et il ne l'importe qu'à un endroit, src/generation/providers.ts, paresseusement. Le cockpit transplanté de la plateforme ne l'importe jamais : il appelle les fonctions serveur de apps/web/src/generation/.

Le dépôt était sur ai@6.0.292. C'est la dernière version de la ligne v6 (étiquette npm ai-v6) ; latest est 7.0.116. Trois besoins du studio ne sont servis que par la v7 :

1. La vidéo asynchrone. La Gateway recommande, pour les fonctions à durée bornée, de démarrer une vidéo puis d'être prévenu ou d'interroger son état (poll, webhook, doStart / doStatus du modèle vidéo). En v6, experimental_generateVideo n'a ni poll ni webhook, et le modèle vidéo de @ai-sdk/gateway@3 n'a pas de doStart. Le lot 4 (vidéo asynchrone, Seedance, Kling) en dépend.
2. La lecture par appel. La v7 range les métadonnées du dernier pas sous finalStep et celles d'une image sous calls : c'est là que se lisent le coût et l'id de génération de la Gateway (G2-05).
3. Le coût de la migration croît avec chaque moteur porté. Aujourd'hui, quatre appels ; après Seedance, Kling, GPT « précis » et les références, une dizaine.

Décision

• packages/engine dépend de ai épinglé à 7.0.116 et de @ai-sdk/gateway épinglé à 4.0.94, la version que ai@7.0.116 fixe lui-même. Épingler les deux garde le fournisseur de la Gateway que le moteur importe (le transport espion des tests, le lot 4) identique à celui que ai utilise pour les chaînes de modèle. Une montée de version est une PR qui change les deux ensemble.
• zod reste en 3.25.76 : la plage de pairs de ai@7 accepte ^3.25.76 || ^4.1.8.
• Les modèles restent des chaînes routées par la Gateway (STUDIO_MODELS, prices.ts), jamais une instance de fournisseur, jamais une clé de fournisseur. Le fournisseur par défaut global du SDK (globalThis.AI_SDK_DEFAULT_PROVIDER) n'est pas posé en production : il sert aux tests pour placer un transport espion sous ces mêmes chaînes.

Les quatre appels migrés

Chaque appel reçoit ses options d'un seul constructeur, packages/engine/src/generation/call-options.ts : clé d'idempotence, attribution, maxRetries explicite, budget d'annulation, utilisateur et étiquettes de la Gateway. Le choix de ces valeurs est expliqué dans Architecture de l’application §7.1.

Conséquences

• Positives : la vidéo asynchrone devient possible sans code de transport maison ; le coût mesuré par la Gateway est lisible là où la v7 le range ; les appels suivent la documentation actuelle au lieu de chemins dépréciés.
• Coût : une dépendance de plus (@ai-sdk/gateway), épinglée. Les API vidéo restent experimental_ en v7 : leur forme peut encore bouger, et la montée de version se fait donc à la main, avec la suite providers.transport.test.ts comme garde.
• Rien ne change pour le cockpit : les fonctions serveur gardent leurs types.

Vérification

• pnpm check au vert sur ai@7.0.116.
• providers.transport.test.ts prouve, requête par requête et sans appel payant, ce que chaque appel envoie à la Gateway.
• live.test.ts reste opt-in (STUDIO_LIVE_E2E=1, LIVE_USD_BUDGET) et dit, pour chaque cas, si la Gateway a rendu un coût.