Developer describes Live/Snapshot/Cache rule and a May 2026 token reset incident

60 jours sous Live/Snapshot/Cache : trois sauvetages, une trahison, et ce que j'ai changé

L'envoi suspendu Mardi 19 mai, dix heures vingt. Je m'apprête à lancer la deuxième vague de SMS de réinscription. Cinquante-trois contacts anciens d'un atelier de céramique, un lien court de la forme /r/<short_code> qui renvoie chacun sur son tunnel personnel. Pré-flight standard : je grep les tokens correspondants pour vérifier qu'ils sont actifs. Cinquante-deux retournent ce que j'attends. Le cinquante-troisième porte un used_at non null, daté du matin même, parce que le tunnel de test que j'avais passé deux heures plus tôt avait consommé le token. Si je lance l'envoi, ce contact reçoit un lien qui répondra 410 Gone. Catherine, qui teste la version mobile depuis l'antenne, m'écrit au même moment qu'elle voudrait que je vérifie « les cinquante-trois quand même, parce que tu sais comment c'est ». Elle a raison. Je n'envoie pas. La règle qui m'avait servi pendant deux mois Depuis la fin avril, je vis sous une règle simple, énoncée en quatre lignes dans la doctrine du projet et que je tiens pour le filet le plus efficace que j'aie posé jusque-là. Toute valeur stockée qui ressemble à une duplication doit être classée Live, Snapshot ou Cache avant d'être créée, et chaque catégorie impose une implémentation différente. Live, c'est ne pas stocker — on lit à la volée via une vue. Snapshot, c'est stocker et ne jamais recalculer — l'historique est intouchable. Cache, c'est stocker mais déclarer dans le même commit le mécanisme de rafraîchissement — trigger nommé, GENERATED ALWAYS AS, ou vue matérialisée. Aucun cache ne survit sans son rafraîchisseur explicite ; si on ne peut pas le garantir, on retombe sur Live. Cette règle est sortie d'un incident d'audit où j'avais découvert qu'une colonne montant_total traînait des écarts à quatre chiffres sur plusieurs centaines de lignes, depuis des semaines, parce que personne ne s'était posé la question. Je ne vais pas re-raconter ce jour-là ; ce qui m'intéresse, c'est ce que la règle a empêché ensuite. Trois fois où la règle a tenu Premier sauvetage, fin avril. Une refonte tarifaire arrive sur la table, et la première intuition d'un script bulk consiste à recalculer rétroactivement la colonne inscriptions.tarif_applique pour aligner toutes les lignes sur la nouvelle grille. Le réflexe est cohérent — on aime la cohérence. Il est fatal. tarif_applique est un Snapshot : le tarif au jour de l'inscription, qui doit rester figé quand le cours est réévalué après. Le recalcul rétroactif vole l'historique, casse le bouclage comptable, et empêche de défendre une facturation contre un parent qui contesterait. La règle dit : recalculer rétroactivement est une faute fonctionnelle, l'évolution s'applique par un nouvel événement, avoir plus nouvelle facture. Le script est réécrit en deux heures, l'historique est conservé, la nouvelle grille s'applique aux inscriptions postérieures à la bascule. Sans le vocabulaire Snapshot, j'aurais accepté le bulk en pensant rendre service à la rigueur. Deuxième sauvetage, mi-mai. Une revue de migration arrive avec une colonne ajoutée à cours pour économiser une jointure dans un export quotidien. Le commit ne contient ni GENERATED ALWAYS AS, ni trigger, ni REFRESH planifié. La règle le rejette automatiquement — pas par moi, par la discipline que je m'impose en review : aucun cache ne survit sans son rafraîchisseur déclaré dans le même commit. La colonne aurait fonctionné le premier jour. Elle aurait dérivé en silence la première fois qu'une inscription serait passée par un chemin qui n'invoquait pas la mise à jour ad hoc. C'est exactement le schéma qui m'avait mis dans le mur sur montant_total ; la règle, cette fois, ferme la porte avant l'incident, pas après. Troisième sauvetage, début mai. Niran arrive avec un compteur agrégé qu'il veut stocker pour ses analyses financières. Hoodie sombre, sa canette de soda posée sur le coin du laptop, il pose la question d'une phrase : « colonne sur cours, ou vue ? ». Je réponds en une phrase aussi : « combien de lignes par lecture, et combien de lectures par minute ? ». Il répond « quelques centaines, peut-être deux par minute ». Vue. Le commit qui suit est une vue v_cours_recettes_mensuelles, pas une colonne. Le calcul à la volée est acceptable côté performance, donc Live, donc vue v_*, pas colonne. Quinze minutes plus tard, le travail est en production, et personne n'a besoin de tenir un rafraîchisseur dans sa tête. Trois sauvetages, trois mécaniques distinctes : un Snapshot qu'on s'apprêtait à profaner, un Cache qu'on s'apprêtait à livrer sans rafraîchisseur, un Live qu'on s'apprêtait à stocker par paresse. La règle a fonctionné précisément parce qu'elle force la question avant le code. La trahison C'est précisément la rigueur de cette règle qui a rendu sa défaillance instructive. Reprenons le matin du 19 mai. Le helper generateTokenForContact cherche un token existant pour le contact, le retourne s'il existe, en crée un sinon. Idempotent par construction. Chacune de ses colonnes a été classée proprement. // lib/reinscription.ts — version avant 07ed02d const { data: existing } = await supabase .from('reinscription_tokens') .select('token, short_code, used_at') .eq('contact_id', contactId) .eq('annee_scolaire', annee) .maybeSingle() if (existing?.token) { return existing.token // ← retourne tel quel, used_at inclus } Le id est un Snapshot — identité figée à la création. Le short_code est un Snapshot — huit caractères base32 générés une fois, jamais regénérés sous peine de casser les SMS déjà envoyés. Le contact_id est un Snapshot. Chaque colonne, prise isolément, est conforme à sa catégorie. La règle est respectée colonne par colonne. Mais used_at est un marqueur Live. Un état transitoire d'usage qui doit refléter la réalité courante du tunnel. Et le helper, en retournant l'objet entier sans toucher used_at, livrait un objet mixte dont le contrat de cohérence n'avait jamais été énoncé. La règle catégorisait des colonnes. Elle ne disait rien sur ce que devient l'objet quand on le ressuscite. Le fix, une fois la trahison comprise, tient en quelques lignes : si on retourne un token existant, on reset used_at à NULL dans la même transaction que le SELECT. // lib/reinscription.ts — commit 07ed02d, 19/05/2026 if (existing.used_at) { await supabase .from('reinscription_tokens') .update({ used_at: null }) .eq('contact_id', contactId) .eq('annee_scolaire', annee) } Le grain de la règle, le grain de l'erreur J'ai mis quelques heures à comprendre ce que cet incident disait, parce que la tentation est de patcher l'endroit et de passer à autre chose. La leçon n'est pas que la règle est fausse ; elle est juste. La leçon est que son grain de classification, la colonne, n'épuisait pas le grain de l'erreur, l'objet métier ressuscité. Un même objet en base porte régulièrement plusieurs colonnes de catégories différentes — Snapshot pour l'identité, Live pour les états transitoires d'usage, parfois Cache pour les agrégats dérivés. Tout helper du type getOrCreate* ou getOrResurrect* qui touche un objet de ce genre doit, dans la même transaction, préserver les Snapshots et reset les Live. Sans cette discipline, la cohérence colonne par colonne se compose en une incohérence d'objet. La v0.7 du toolkit l'a entériné en posant une règle projet juste à côté de R6, plutôt qu'en réécrivant R6. Hybrid Snapshot/Live reset — quatre paragraphes, un tableau de cas applicables, un test contrat associé qui exige un cas négatif. Pas une refonte. Une extension qui reconnaît que R6 décrit l'état statique d'une colonne et que les helpers qui ressuscitent un objet introduisent une dynamique transitionnelle que R6 ne couvrait pas. // pattern minimal hybrid-snapshot-live-reset async function getOrResurrectToken(contactId: string): Promise<Token> { const existing = await supabase .from('reinscription_tokens') .select('*') .eq('contact_id', contactId) .maybeSingle() if (existing.data) { // Identity (Snapshot) — keep. Live markers (used_at) — reset. if (existing.data.used_at !== null) { await supabase .from('reinscription_tokens') .update({ used_at: null }) .eq('id', existing.data.id) } return existing.data } return await createToken(contactId) } C'est ce qui a changé en deux mois. Pas la règle elle-même, qui continue de tenir trois fois pour une où elle échoue. Une clause projet qui ferme la classe d'incidents qu'elle ne savait pas couvrir. Le toolkit lui-même obéit à sa propre R6 sur ce point : la doctrine est Live, pas dupliquée — la règle mère reste générique, l'extension vit dans le projet où elle s'applique, et migre en haut seulement si trois projets indépendants la valident. Coda Je n'ai pas envoyé l'envoi de la matinée. J'ai reset le token, relancé le grep, vu cinquante-trois lignes propres, puis envoyé. Catherine m'a répondu « hum ça bug, mais c'est vite corrigé » d'une voix neutre. Ce n'était pas un bug, c'était une règle qui n'avait pas pris le grain de l'objet. Trois sauvetages, une trahison : la règle ne s'évalue pas au taux de succès, elle s'évalue à la qualité des extensions qu'elle accepte quand elle se fait surprendre. Si la mienne se fait surprendre une fois sur trois et que l'extension tient en quatre paragraphes, je continue. Article #61 de la série Mon ERP avec Claude Code. Counterpart Toolkit v0.7, règle R6 Live/Snapshot/Cache mandatory, extension projet hybrid-snapshot-live-reset publiée le 19 mai 2026. Le repo de doctrine reste sous CC-BY-4.0.

1 hour ago

Live, Snapshot, Cache: revisiting the 3-way decision after 60 days of running it

The send put on hold Tuesday May 19, ten twenty in the morning. I'm about to launch the second SMS wave of the re-enrollment campaign. Fifty-three former contacts from a ceramics workshop, a short link /r/<short_code> that sends each one to their personal funnel. Standard pre-flight: I grep the corresponding tokens to verify they're active. Fifty-two return what I expect. The fifty-third carries a non-null used_at, dated the same morning, because the test funnel I had gone through two hours earlier had consumed the token. If I launch the send, this contact receives a link that will answer 410 Gone. Catherine, testing the mobile version from the branch, writes me at the same moment to say she'd like me to check "the fifty-three anyway, because you know how it is". She's right. I don't send. The rule that had served me for two months Since late April, I've lived under a simple rule, stated in four lines in the project doctrine and that I hold as the most effective net I've laid down so far. Any stored value that resembles a duplication must be classified Live, Snapshot or Cache before being created, and each category imposes a different implementation. Live means don't store — read on the fly via a view. Snapshot means store and never recalculate — history is untouchable. Cache means store but declare the refresh mechanism in the same commit — named trigger, GENERATED ALWAYS AS, or materialised view. No cache survives without its explicit refresher; if you can't guarantee it, you fall back to Live. This rule came out of an audit incident where I had discovered that a montant_total column carried four-digit discrepancies on several hundred rows, for weeks, because nobody had asked the question. I won't re-tell that day; what interests me is what the rule prevented afterwards. Three times the rule held First save, late April. A pricing overhaul lands on the table, and the first intuition of a bulk script is to retroactively recalculate the inscriptions.tarif_applique column to align all rows on the new grid. The reflex is coherent — we like coherence. It's fatal. tarif_applique is a Snapshot: the price at the day of enrollment, that must stay frozen when the course is reassessed afterwards. Retroactive recalculation steals history, breaks accounting reconciliation, and prevents defending a billing against a parent who'd contest it. The rule says: retroactive recalculation is a functional fault; evolution applies through a new event, credit note plus new invoice. The script is rewritten in two hours, history is preserved, the new grid applies to enrollments after the cutover. Without the Snapshot vocabulary, I would have accepted the bulk thinking I was doing rigour a favour. Second save, mid May. A migration review arrives with a column added to cours to save a join in a daily export. The commit contains neither GENERATED ALWAYS AS, nor trigger, nor scheduled REFRESH. The rule rejects it automatically — not by me, by the discipline I impose on myself in review: no cache survives without its refresher declared in the same commit. The column would have worked the first day. It would have drifted silently the first time an enrollment came through a path that didn't invoke the ad hoc update. That's exactly the pattern that drove me into the wall on montant_total; the rule, this time, closes the door before the incident, not after. Third save, early May. Niran arrives with an aggregate counter he wants to store for his financial analyses. Dark hoodie, his soda can on the corner of the laptop, he asks the question in one phrase: "column on cours, or view?". I answer in one phrase too: "how many rows per read, and how many reads per minute?". He answers "a few hundred, maybe two per minute". View. The commit that follows is a v_cours_recettes_mensuelles view, not a column. The on-the-fly compute is acceptable performance-wise, so Live, so v_* view, not column. Three saves, three distinct mechanics: a Snapshot we were about to profane, a Cache we were about to ship without a refresher, a Live we were about to store out of laziness. The rule worked precisely because it forces the question before the code. The betrayal It's precisely the rigour of this rule that made its failure instructive. Back to Tuesday May 19. The helper generateTokenForContact looks for an existing token for the contact, returns it if it exists, creates one otherwise. Idempotent by construction. Each of its columns has been classified properly. // lib/reinscription.ts — version before 07ed02d const { data: existing } = await supabase .from('reinscription_tokens') .select('token, short_code, used_at') .eq('contact_id', contactId) .eq('annee_scolaire', annee) .maybeSingle() if (existing?.token) { return existing.token // ← returns as-is, used_at included } The id is a Snapshot — identity frozen at creation. The short_code is a Snapshot — eight base32 characters generated once, never regenerated under penalty of breaking already-sent SMS. The contact_id is a Snapshot. Each column, taken in isolation, is conformant to its category. The rule is respected column by column. But used_at is a Live marker. A transient usage state that must reflect the funnel's current reality. And the helper, returning the entire object without touching used_at, delivered a mixed object whose coherence contract had never been stated. The rule classified columns. It said nothing about what happens to the object when we resurrect it. The fix, once the betrayal understood, fits in a few lines: if we return an existing token, we reset used_at to NULL in the same transaction as the SELECT. // lib/reinscription.ts — commit 07ed02d, 19/05/2026 if (existing.used_at) { await supabase .from('reinscription_tokens') .update({ used_at: null }) .eq('contact_id', contactId) .eq('annee_scolaire', annee) } The grain of the rule, the grain of the error It took me a few hours to understand what this incident said, because the temptation is to patch the spot and move on. The lesson is not that the rule is wrong; it's right. The lesson is that its classification grain — the column — did not exhaust the error grain — the resurrected business object. The same object in the database regularly carries multiple columns of different categories — Snapshot for identity, Live for transient usage states, sometimes Cache for derived aggregates. Any helper of the getOrCreate* or getOrResurrect* type that touches such an object must, in the same transaction, preserve Snapshots and reset Lives. Without this discipline, column-by-column coherence composes into object incoherence. The v0.7 toolkit ratified this by laying a project rule right next to R6, rather than by rewriting R6. Hybrid Snapshot/Live reset — four paragraphs, a table of applicable cases, an associated contract test that requires a negative case. Not a refactor. An extension that recognises R6 describes the static state of a column and that helpers resurrecting an object introduce a transitional dynamic R6 didn't cover. // minimal hybrid-snapshot-live-reset pattern async function getOrResurrectToken(contactId: string): Promise<Token> { const existing = await supabase .from('reinscription_tokens') .select('*') .eq('contact_id', contactId) .maybeSingle() if (existing.data) { // Identity (Snapshot) — keep. Live markers (used_at) — reset. if (existing.data.used_at !== null) { await supabase .from('reinscription_tokens') .update({ used_at: null }) .eq('id', existing.data.id) } return existing.data } return await createToken(contactId) } That's what changed in two months. Not the rule itself, which keeps holding three times for one failure. A project clause that closes the incident class it couldn't cover. The toolkit obeys its own R6 on this point: doctrine is Live, not duplicated — the mother rule stays generic, the extension lives in the project where it applies, and migrates upward only when three independent projects validate it. Coda I didn't launch the morning send. I reset the token, reran the grep, saw fifty-three clean lines, then sent. Catherine answered "hum it bugs, but it's quickly fixed" in a neutral voice. It wasn't a bug, it was a rule that hadn't taken the object's grain. Three saves, one betrayal: a rule isn't evaluated by its success rate, it's evaluated by the quality of the extensions it accepts when it gets surprised. If mine gets surprised one time in three and the extension fits in four paragraphs, I keep going. Article #61 of the series My ERP with Claude Code. Counterpart Toolkit v0.7, rule R6 Live/Snapshot/Cache mandatory, project extension hybrid-snapshot-live-reset published May 19, 2026. The doctrine repo remains CC-BY-4.0.

1 hour ago