Temps & Planification

Vous pouvez définir des minuteurs (~minuteur) et des durées dans vos recettes à l'aide du symbole ~.

Déclaration de Base

Un ~minuteur doit spécifier une unité à l'intérieur des accolades. Un texte imprécis comme ~{environ 10 minutes} est invalide.

Cuire pendant ~{25 min}.

Unités supportées :

• min (minutes) - Standard recommandé.
• h (heures).
• d (jours).
• s (secondes).

Note : m ou minutes seront automatiquement corrigés en min par le compilateur.

Ces unités sont résolues via le dictionnaire de temps multilingue de Gram : les alias localisés ci-dessous sont donc également reconnus pour un ~minuteur, quelle que soit la langue de rédaction de la recette (ex : ~{2j} fonctionne exactement comme ~{2d}).

Canonique	Alias
d	j, jour, jours
h	heure, heures
m	min, mins, minute, minutes
s	sec, secs, seconde, secondes

Noms de Minuteur

Vous pouvez attribuer un nom spécifique à un ~minuteur. C'est particulièrement utile pour les tâches passives : lorsque plusieurs ~minuteurs s'exécutent en parallèle (comme une pâte qui repose pendant qu'une sauce mijote), les noms permettent aux outils et aux interfaces d'affichage de les identifier et de les suivre clairement de manière simultanée.

Faire bouillir les @œufs{2} pendant ~œufs{3 min}.

Plages (Intervalles)

Vous pouvez spécifier une plage de temps si la durée est une estimation.

Cuire au four pendant ~{30-40 min}.

TIP

Pour les calculs globaux de la ligne du temps (durée totale de la recette), le compilateur utilise automatiquement la moyenne de la plage (ici, 35 minutes).

Actif vs Passif

Le compilateur Gram construit une ligne du temps complète (similaire à un diagramme de Gantt) de l'exécution de votre recette. Pour le faire avec précision, il a besoin de savoir si un ~minuteur nécessite votre attention complète ou s'il s'exécute en arrière-plan.

💡 La Règle d'Or : Est-ce que cette étape VOUS empêche de commencer l'étape suivante ?

Votre Statut	Type de Minuteur	Syntaxe	Exemples
OUI (Attention manuelle requise)	Actif	~	Fouetter à la main, remuer un risotto
NON (Une machine/le temps fait le travail)	Passif	~_	Cuisson au four, repos, robot pâtissier

Actif (Par défaut)

Par défaut, un ~minuteur est actif. Cela implique que vous travaillez activement et cela bloque le flux de travail. Vous devez terminer cette étape avant de pouvoir faire autre chose.

Fouetter la @crème liquide{} en continu pendant ~{5 min}.

⏱️ Résultat : Ajoute 5 minutes au Temps Actif.

Passif (_)

Utilisez le modificateur _ pour rendre un ~minuteur passif. C'est une tâche en arrière-plan. Vous démarrez le ~minuteur (ex : mettre un plat au four) et passez immédiatement à l'étape suivante.

Cuire dans le #four pendant ~_{45 min}.

Pendant ce temps, préparer le glaçage...

⏱️ Résultat : N'ajoute aucune (0) minute au Temps Actif, mais garantit que le Temps de Cuisson est prolongé pour couvrir cette attente de 45 minutes.

Timers Passifs Séquentiels (Les "Named Tracks")

Par défaut, les timers passifs s'exécutent en parallèle du reste de votre recette. Cependant, certaines tâches de fond ne peuvent pas physiquement s'exécuter en même temps (ex: cuire un gâteau pendant 10 minutes, puis baisser la température et cuire encore 30 minutes).

Si vous voulez que vos timers passifs s'exécutent de façon séquentielle (l'un après l'autre), il suffit de leur donner le même nom :

Cuire dans le four à 240°C pendant ~_cuisson{10 min}.

Baisser la température à 180°C et cuire pendant ~_cuisson{30 min}.

⏱️ Résultat : Comme ces deux timers partagent le nom cuisson, Gram les place sur la même "piste" de fond. Le timer de 30 minutes démarrera automatiquement après la fin des 10 premières minutes. Le temps total d'Attente augmentera bien de 40 minutes, sans impacter votre Temps Actif (qui reste à zéro) !

Comment le Temps est Calculé

En coulisses, Gram calcule quatre métriques de temps distinctes pour vous donner un planning de cuisine réaliste.

⏱️ Les 4 Métriques de Temps

1. Temps de Préparation (Mise-en-place) : Temps nécessaire avant de commencer l'étape 1 (rassembler les ingrédients, éplucher, couper).
2. Temps Actif : Temps passé à travailler activement pendant les étapes de la recette (les mains occupées).
3. Temps de Cuisson : Le temps absolu du flux de la recette, de l'étape 1 jusqu'à la fin (incluant l'attente passive).
4. Temps Total : La somme du Temps de Préparation + Temps de Cuisson. C'est le "temps passé en cuisine" réaliste.

Antisèche : Qu'est-ce qui ajoute du temps ?

Voici une décomposition concrète de la manière dont le compilateur calcule automatiquement les minutes en fonction de votre syntaxe :

Syntaxe / Scénario	Ajoute au Temps de Préparation	Ajoute au Temps Actif	Ajoute au Temps de Cuisson	Ajoute au Temps Total
Nouvel Ingrédient (@farine)	+ 1 min	-	-	+ 1 min
Préparation courte (@oignon(épluché))	+ 2 min	-	-	+ 2 min
Minuteur Actif (~{10 min})	-	+ 10 min	+ 10 min	+ 10 min
Minuteur Passif (~_{1 h})	-	-	+ 1 heure (en arrière-plan)	+ 1 heure
Étape sans aucun minuteur	-	+ 2 min (valeur par défaut)	+ 2 min	+ 2 min

Suivi Intelligent des Dépendances (ALAP)

Vous n'avez pas besoin de faire des mathématiques complexes ! Gram utilise un algorithme d'ordonnancement ALAP (As Late As Possible). Si vous déclarez une pâte qui repose pendant ~_{1 h} en arrière-plan, et qu'une étape ultérieure requiert cette &pâte, le compilateur repousse automatiquement la préparation de la pâte le plus tard possible. La pâte finira de reposer exactement au moment où l'étape suivante commence, évitant ainsi qu'elle ne patiente inutilement sur le plan de travail !

Pour une explication plus détaillée de l'optimisation de la ligne du temps, consultez l'Analyse approfondie de l'Ordonnancement ALAP.

Rétroplanning de Section

Vous pouvez assigner un délai de préparation à une ## Section en ajoutant une annotation ~{...} à son titre. Cela permet d'indiquer au compilateur quand cette section doit se terminer par rapport à son utilisation finale.

Ceci agit comme une ancre temporelle. En ajoutant ~{-2j} à une section, vous indiquez au compilateur que cette préparation doit être effectuée 2 jours avant d'être réellement utilisée.

Pour que la chronologie générée reste cohérente et que les temps absolus soient positifs (commençant à 0), le compilateur réinitialise automatiquement le calcul des temps (timings) : cette préparation faite en avance devient le nouveau point de départ (Temps 0) de la recette, et toutes les étapes de cuisson suivantes sont décalées proportionnellement. C'est l'outil parfait pour gérer des recettes sur plusieurs jours tout en gardant une structure de données exploitable par les interfaces.

## Pâte Feuilletée ~{-2j}

Cela signifie que la section "Pâte Feuilletée" doit être préparée 2 jours à l'avance.

Syntaxe stricte

Contrairement à du texte libre, ~{...} sur un titre de section exige un nombre strictement négatif suivi d'une unité — puisque cette annotation sert spécifiquement à indiquer combien de temps à l'avance la section doit être préparée, une valeur nulle ou positive n'aurait pas de sens ici :

• Un - obligatoire en préfixe (l'anticipation est tout l'intérêt du rétroplanning).
• Un nombre non nul.
• Une unité : d (jours), h (heures), ou min (minutes) — les mêmes unités canoniques que la version anglaise ; voir la note ci-dessous sur les alias localisés comme j.

## Pâte Feuilletée ~{-2j}   <!-- 2 jours avant -->
## Ganache ~{-30min}        <!-- 30 minutes avant -->

Un texte libre (ex : ~{la veille}/~{the day before}), une valeur non signée ou positive (ex : ~{2h}), et une valeur nulle (ex : ~{0h} ou ~{-0h}) ne sont plus valides pour cette annotation — écrivez ~{-1j} à la place. Les recettes existantes utilisant l'une de ces formes continuent de compiler, mais le compilateur les signale désormais comme décrit ci-dessous.

L'unité est résolue via le même dictionnaire de temps multilingue que celui utilisé par ~minuteur (voir Déclaration de Base) : j, jour et jours sont tous reconnus comme alias de l'unité canonique d (jour), quelle que soit la langue de rédaction de la recette.

Voir aussi : Rétroplanning (Ordonnancement) dans la référence de structure de document.

Gestion des Erreurs

Le compilateur valide les déclarations de ~minuteur et les annotations de rétroplanning de section pour garantir une planification précise, et produira des avertissements spécifiques pour des données mal formées :

• Unité Manquante (~minuteur) : Si vous écrivez ~{30} sans préciser s'il s'agit de minutes ou d'heures, le compilateur avertit MISSING_UNIT.
• Unité Invalide (~minuteur) : Si vous fournissez une unité que le compilateur ne comprend pas (ex : ~{30 années-lumière}), il avertit INVALID_UNIT.
• Unité Manquante (rétroplanning de section) : ~{-2}, du texte libre comme ~{la veille}, une valeur non signée ou positive (~{2h}), ou une valeur nulle (~{0h}, ~{-0h}) déclenchent tous MISSING_UNIT — aucun n'est une durée signée strictement négative.
• Unité Invalide (rétroplanning de section) : une unité non reconnue (ex : ~{-2 années-lumière}) déclenche INVALID_UNIT.
• Paradoxe Temporel : Si une ancre de rétro-planning de section entre en conflit avec une dépendance requise plus tôt (ex: une section ancrée à -10 min mais utilisée dans une section ancrée à -1 h), le compilateur avertit TIME_PARADOX.
• Contention de Pistes : Si vous utilisez des timers passifs nommés (ex: ~_four{30min}) et que l'algorithme ALAP se voit forcé de les retarder à cause d'un encombrement (plusieurs timers sur la même piste au même moment), le compilateur avertit TRACK_CONTENTION.

Pour le rétroplanning de section, l'annotation d'origine reste affichée telle quelle même en cas d'avertissement. Dans tous les cas, ces avertissements sont non bloquants par défaut (la recette compile toujours), mais sont promus en erreurs bloquantes avec gram check --strict.