discovery-media-player 0.1.162 → 0.1.164

package/context/standalone.js

@@ -41,6 +41,72 @@ function sansBarreFinale(valeur) {
 }
 
 /** Client REST minimal (PostgREST). Absent de configuration ⇒ chaque appel échoue franchement. */
+/**
+ * ⚠️ UN SEUL ENDROIT QUI BORNE, PARCE QU'IL Y EN AVAIT UN SUR QUATRE.
+ *
+ * `db.request` abandonnait déjà après un délai, avec le raisonnement écrit à côté : sans signal, un
+ * service qui accepte la connexion et ne répond plus immobilise la requête, sa socket ET la place
+ * d'admission jusqu'à ce que la plateforme tue la fonction. Trois autres appels — suppression
+ * Storage, signature d'envoi, vérification de jeton — partaient nus. Un audit externe l'a mesuré le
+ * 11/09 en remplaçant `fetch` : `REST hasSignal true`, les trois autres `false`.
+ *
+ * ⚠️ CE N'EST PAS UN CONTOURNEMENT D'AUTORISATION : ces chemins refusent en cas d'échec, ils rendent
+ * `null` ou `false`. Le risque est de DISPONIBILITÉ — sous concurrence, des sockets, de la mémoire
+ * et des exécutions serverless retenues par un tiers lent, y compris pour les purges et les
+ * consultations protégées.
+ *
+ * ⚠️ ET UNE COURSE DE PROMESSES NE SUFFIRAIT PAS : elle rendrait la main sans ANNULER le `fetch`,
+ * donc sans rien libérer. C'est `AbortSignal` ou rien. Un signal fourni par l'appelant s'AJOUTE au
+ * plancher — voir `composerSignaux` : le premier des deux qui parle gagne.
+ */
+/**
+ * ⚠️ ON COMPOSE LES SIGNAUX, ON NE LES REMPLACE PAS — ET LA PREMIÈRE ÉCRITURE LES REMPLAÇAIT.
+ *
+ * Elle disait `options.signal || AbortSignal.timeout(delai)` : un signal fourni par l'appelant
+ * SUPPRIMAIT le plancher, au lieu de s'y ajouter. Un hôte qui borne lui-même une opération longue
+ * croyait donc ajouter une garantie, et en retirait une. Mesuré : avec un signal qui n'expire jamais
+ * et `timeoutMs: 20`, la promesse est encore en attente après 150 ms.
+ *
+ * ⚠️ ET LE COMMENTAIRE BÉNISSAIT LE DÉFAUT. Il écrivait « un signal fourni par l'appelant a
+ * priorité — un hôte qui borne lui-même une opération longue n'est pas écrasé ». L'intention est
+ * juste ; « a priorité » était la mauvaise traduction. Le premier des deux qui parle gagne : c'est
+ * ce que « borner » veut dire. Rapporté par un audit externe le 12/09 comme défaut LATENT — aucun
+ * appel du produit ne transmet aujourd'hui de signal, donc personne ne l'aurait vu arriver.
+ */
+function composerSignaux(fourni, delaiMs) {
+  const horloge = (typeof AbortSignal !== "undefined" && AbortSignal.timeout)
+    ? AbortSignal.timeout(delaiMs) : undefined;
+  if (!fourni) return horloge;
+  if (!horloge) return fourni;
+  if (typeof AbortSignal.any === "function") return AbortSignal.any([fourni, horloge]);
+  // ⚠️ REPLI SANS `AbortSignal.any` : un contrôleur qui suit les deux. Le `aborted` se teste AVANT
+  // de s'abonner — un signal déjà déclenché n'émettra plus jamais son événement, et l'attendre
+  // serait une attente infinie posée par la précaution elle-même.
+  const relais = new globalThis.AbortController();
+  const abandonner = () => { try { relais.abort(); } catch { /* déjà abandonné */ } };
+  for (const s of [fourni, horloge]) {
+    if (s.aborted) { abandonner(); break; }
+    try { s.addEventListener("abort", abandonner, { once: true }); } catch { /* signal exotique */ }
+  }
+  return relais.signal;
+}
+
+function fetchBorne(cible, options = {}, delaiMs) {
+  const signal = composerSignaux(options.signal, delaiMs);
+  return fetch(cible, { ...options, ...(signal ? { signal } : {}) });
+}
+
+/**
+ * Les délais, nommés plutôt qu'écrits en clair sur l'appel. ⚠️ ILS NE SONT PAS ÉGAUX, ET C'EST LE
+ * SUJET : une vérification de jeton est sur le chemin d'une réponse qu'un visiteur attend, un
+ * transfert vers Storage ne l'est pas. Un délai unique ferait patienter le visiteur au rythme du
+ * service le plus lent.
+ */
+const DELAI_AUTH_MS = 5000;
+const DELAI_ROUTE_HOTE_MS = 4000;
+const DELAI_STOCKAGE_MS = 15000;
+const DELAI_BASE_MS = 15000;
+
 function creerDb(env) {
   const url = sansBarreFinale(env.SUPABASE_URL);
   const cle = String(env.SUPABASE_SERVICE_ROLE_KEY || "");
@@ -67,12 +133,10 @@ function creerDb(env) {
     // transforme un ralentissement en refus général. Une course `Promise.race` ne suffirait pas —
     // elle rendrait la main sans ANNULER le fetch, donc sans libérer quoi que ce soit. L'hôte peut
     // fournir son propre `signal` (opérations longues : purges, transferts). (Audit externe.)
-    const delai = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : 15000;
-    const signal = options.signal || (typeof AbortSignal !== "undefined" && AbortSignal.timeout
-      ? AbortSignal.timeout(delai) : undefined);
-    const r = await fetch(`${url}/rest/v1/${chemin}`, {
+    const delai = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : DELAI_BASE_MS;
+    const r = await fetchBorne(`${url}/rest/v1/${chemin}`, {
       method: methode,
-      ...(signal ? { signal } : {}),
+      ...(options.signal ? { signal: options.signal } : {}),
       headers: {
         apikey: cle,
         Authorization: `Bearer ${cle}`,
@@ -80,7 +144,7 @@ function creerDb(env) {
         ...(options.headers || {}),
       },
       body: options.body ? JSON.stringify(options.body) : undefined,
-    });
+    }, delai);
     if (!r.ok) {
       // ⚠️ LE CORPS DIT POURQUOI, LE CODE NE DIT QUE COMBIEN. Un « 400 » nu a coûté un aller-retour
       // de forge complet pour apprendre ce que PostgREST avait écrit dans sa réponse depuis le
@@ -166,15 +230,14 @@ async function appelHote(url, secret, corps, errors) {
   // perdu exactement ce temps-là.
   const signaler = (quoi) => { try { errors && errors.capture(new Error(`route hôte : ${quoi}`), { url }); } catch { /* jamais bloquant */ } };
   try {
-    const r = await fetch(url, {
+    const r = await fetchBorne(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         ...(secret ? { "x-player-fetch-secret": secret } : {}),
       },
       body: JSON.stringify(corps),
-      signal: AbortSignal.timeout(4000), // une décision qui tarde est une décision absente
-    });
+    }, DELAI_ROUTE_HOTE_MS); // une décision qui tarde est une décision absente
     if (!r.ok) { signaler(`réponse ${r.status}`); return null; }
     const d = await r.json().catch(() => null);
     if (!d || typeof d !== "object") { signaler("réponse illisible (JSON attendu)"); return null; }
@@ -211,13 +274,33 @@ async function appelHote(url, secret, corps, errors) {
  * base. Y adosser un compteur partagé ferait payer à la garde le prix qu'on venait d'épargner à ce
  * qu'elle garde. Sur ce chemin, la protection réelle est le cache, pas le compteur.
  *
- * ⚠️ LE COMPTE PARTAGÉ N'EST PAS ATOMIQUE. PostgREST ne sait pas exprimer « incrémente » : c'est une
- * lecture puis une écriture. Deux instances peuvent donc lire la même valeur et n'en écrire qu'une —
- * le compteur SOUS-estime sous forte concurrence. Pour une limite de débit, sous-estimer signifie
- * laisser passer un peu plus, jamais refuser à tort. Le dire vaut mieux que laisser croire à une
- * exactitude qu'on n'a pas.
+ * ⚠️ CE PARAGRAPHE DISAIT QUE LE COMPTE PARTAGÉ N'EST PAS ATOMIQUE. C'EST FAUX DEPUIS 0004, et il
+ * a survécu à ce qu'il décrivait — écrit quand PostgREST ne savait pas exprimer « incrémente »,
+ * donc quand compter était une lecture puis une écriture. La migration `0004-limites-atomiques.sql`
+ * a remplacé les deux par UNE instruction serveur : `player_rate_limit_bump`. Corrigé plutôt que
+ * supprimé, parce qu'un hôte qui l'a lu a pu bâtir une compensation dont il n'a pas besoin.
+ *
+ * ⚠️ ET LA DÉGRADATION RÉELLE EST L'INVERSE DE CE QU'IL LAISSAIT CROIRE. Sans 0004, l'étage partagé
+ * ne compte pas moins bien : IL NE COMPTE PAS DU TOUT. Le `return true` plus bas laisse passer, et
+ * seul le compteur LOCAL, par processus, subsiste — une limite de 120/h en autorise 120 PAR
+ * EXÉCUTION. « Non atomique » nommait un mode qui n'existe pas : un comptage partagé dégradé.
+ *
+ * La matrice complète est dans `docs/HOST-CONTRACT.md` ; elle est la version qui fait foi.
+ *
+ * ⚠️ CETTE PHRASE-CI EST LE JUMEAU FRANÇAIS DE CELLE CORRIGÉE DANS LE CONTRAT LE 11/09 — À 95
+ * LIGNES DE L'AVERTISSEMENT CORRIGÉ LE MÊME JOUR, DANS CE MÊME FICHIER. Corriger un exemplaire
+ * d'une affirmation et pas l'autre est le mode de panne que ce dépôt traque partout ailleurs : deux
+ * copies d'une règle divergent, et personne ne les confronte. Cherchez le MÉCANISME que vous venez
+ * de changer, pas les mots dont vous vous souvenez.
+ */
+/**
+ * @param horloge lecture du temps, injectable. ⚠️ ELLE EXISTE POUR QU'UN BANC N'AIT PAS À REMPLACER
+ * `Date.now` GLOBALEMENT. Une simulation d'une heure d'audience doit faire avancer le temps ; le
+ * seul moyen était de rustiner un global, ce qui laisse l'instrument dépendre d'un `finally` posé au
+ * bon endroit — et la première écriture de cette simulation l'avait posé au mauvais, mesurant en
+ * partie le temps RÉEL sans le dire. Une horloge passée en argument ne peut pas fuir.
  */
-function creerLimites(db, journal) {
+function creerLimites(db, journal, horloge = () => Date.now()) {
   const seaux = new Map();
   const PREFIXES_LOCAUX = ["pread:"];
   let partageDisponible = null;   // null = pas encore demandé
@@ -231,7 +314,7 @@ function creerLimites(db, journal) {
   // anti-inondation, et c'est le compromis explicitement recommandé.
   const PLAFOND_CLES = 5000;
   function localAutorise(cle, max, fenetreSecondes) {
-    const maintenant = Date.now();
+    const maintenant = horloge();
     const fenetreMs = fenetreSecondes * 1000;
     let e = seaux.get(cle);
     if (!e || maintenant - e.debut >= fenetreMs) e = { debut: maintenant, compte: 0 };
@@ -306,8 +389,14 @@ function creerLimites(db, journal) {
         // passer ; dans les deux cas on le dit, en NOMMANT le fichier à appliquer. C'est la règle
         // du chemin de migration : dégrader, jamais casser, et ne jamais dégrader en silence.
         prevenirUneFois(
-          "compteurs de débit non atomiques : appliquez supabase/migrations/0004-limites-atomiques.sql. "
-          + "Sans elle, plusieurs requêtes simultanées peuvent dépasser la limite ensemble. "
+          // ⚠️ CE MESSAGE NOMMAIT UN MODE QUI N'EXISTE PAS. Il disait « compteurs non atomiques »,
+          // ce qui décrit un comptage partagé plus faible. Or ici il n'y a PLUS de comptage partagé
+          // du tout : le `return true` ci-dessous laisse passer, et seul l'étage local subsiste.
+          // Dire « non atomique » laisse croire qu'un plafond d'instance tient encore, en moins
+          // précis. Trouvé par un audit externe le 11/09, avec la contradiction jumelle du contrat.
+          "compteur de débit PARTAGÉ INDISPONIBLE : appliquez supabase/migrations/0004-limites-atomiques.sql. "
+          + "Sans elle il ne reste que le compteur LOCAL, par processus — une limite de 120/h en "
+          + "autorise 120 PAR EXÉCUTION. Ce n'est pas un comptage partagé dégradé, c'est aucun. "
           + "(" + ((erreur && erreur.message) || erreur) + ")",
         );
         return true;
@@ -352,16 +441,48 @@ function createStandaloneContext(env = process.env) {
         // ⚠️ DERNIÈRE BARRIÈRE avant un DELETE à la clé service_role (P1 huitième audit). Bucket en
         // liste blanche, et refus de toute traversée — chaque segment sur l'alphabet des chemins
         // signés. `fetch` normalise `..` : un chemin non validé sortirait du bucket visé.
-        if (bucket !== "present-attachments") return false;
+        //
+        // ⚠️ LA LISTE NE PORTAIT QU'UN BUCKET SUR LES DEUX, ET LA PURGE DU CACHE DE VOIX N'A DONC
+        // JAMAIS RIEN RETIRÉ. `tts-cache` était refusé ICI, avant tout appel réseau : chaque retrait
+        // rendait `false`, la trace partait quand même, et l'objet restait dans un bucket PUBLIC
+        // sans plus aucun chemin vers lui — puisque cette capacité expose `put` et `remove`, jamais
+        // `list`. C'est très exactement le mal que la migration 0021 avait été écrite pour rendre
+        // réparable, à 100 %, en silence.
+        //
+        // ⚠️ ET CE SILENCE ÉTAIT DOCUMENTÉ. Le rapport comptait ces refus dans `fichiersErreur`, que
+        // `docs/RETENTION.md` explique par un fait vrai — un tiers des empreintes n'a pas de `.json`
+        // d'alignement (552 mp3 pour 356 json, mesuré par un hôte). Une explication JUSTE rendait
+        // donc un échec TOTAL indiscernable d'un fonctionnement normal. Trouvé le 12/09 en écrivant
+        // la documentation du correctif d'un AUTRE défaut du même chemin.
+        //
+        // La liste énumère maintenant les deux buckets que la rétention doit atteindre, et rien
+        // d'autre : la barrière garde son objet, elle cesse d'interdire le travail qu'on lui demande.
+        if (bucket !== "present-attachments" && bucket !== "tts-cache") return false;
         const segs = String(chemin).split("/");
         for (const seg of segs) {
           if (seg === "" || seg === "." || seg === ".." || !/^[A-Za-z0-9._-]+$/.test(seg)) return false;
         }
         try {
-          const r = await fetch(`${base}/storage/v1/object/${encodeURIComponent(bucket)}/${segs.map(encodeURIComponent).join("/")}`, {
+          const r = await fetchBorne(`${base}/storage/v1/object/${encodeURIComponent(bucket)}/${segs.map(encodeURIComponent).join("/")}`, {
             method: "DELETE", headers: { apikey: cle, Authorization: `Bearer ${cle}` },
-          });
-          return r.ok;
+          }, DELAI_STOCKAGE_MS);
+          if (r.ok) return true;
+          // ⚠️ UN OBJET DÉJÀ ABSENT EST UN SUCCÈS POUR CE QU'ON DEMANDE ICI, ET CE N'EST PLUS UNE
+          // NUANCE DE COMPTAGE. La purge RETIENT désormais la ligne quand ce
+          // retrait rend `false`, parce que la ligne est le seul chemin vers l'objet (`storage`
+          // expose `put` et `remove`, jamais `list`). Rendre `false` sur un objet qui n'est plus là
+          // retiendrait donc la ligne POUR TOUJOURS, en attendant un fichier qui n'existe pas —
+          // exactement la sur-rétention que le correctif de la sous-rétention ne doit pas créer.
+          // Ce qu'on demande est « l'objet n'est plus là », et il n'y est plus.
+          //
+          // ⚠️ ON LIT LE CORPS PARCE QUE LE CODE NE SUFFIT PAS. Le Storage de Supabase répond 400
+          // sur un objet manquant, pas seulement 404 : se fier au seul statut raterait le cas le
+          // plus fréquent. NON VÉRIFIÉ CONTRE UN SUPABASE VIVANT DEPUIS CE DÉPÔT — ce qui est
+          // éprouvé ici est la CORRESPONDANCE (statut et corps vers verdict), pas la forme exacte
+          // que le fournisseur émet. Un hôte qui observerait une autre formulation doit la dire.
+          if (r.status === 404) return true;
+          const corps = await r.text().catch(() => "");
+          return /not[_ ]?found|no such key|does not exist/i.test(corps);
         } catch { return false; }
       },
 
@@ -382,11 +503,11 @@ function createStandaloneContext(env = process.env) {
         const cle = String(env.SUPABASE_SERVICE_ROLE_KEY || "");
         if (!base || !cle || !bucket || !chemin) return null;
         try {
-          const r = await fetch(`${base}/storage/v1/object/upload/sign/${bucket}/${chemin}`, {
+          const r = await fetchBorne(`${base}/storage/v1/object/upload/sign/${bucket}/${chemin}`, {
             method: "POST",
             headers: { apikey: cle, Authorization: `Bearer ${cle}`, "Content-Type": "application/json" },
             body: "{}",
-          });
+          }, DELAI_STOCKAGE_MS);
           if (!r.ok) return null;
           const d = await r.json().catch(() => null);
           const url = d && d.url;
@@ -474,9 +595,9 @@ function createStandaloneContext(env = process.env) {
         }
         if (!jeton || !url || !cle) return null;
         try {
-          const r = await fetch(`${url}/auth/v1/user`, {
+          const r = await fetchBorne(`${url}/auth/v1/user`, {
             headers: { apikey: cle, Authorization: `Bearer ${jeton}` },
-          });
+          }, DELAI_AUTH_MS);
           return r.ok ? await r.json() : null;
         } catch { return null; }
       },

package/context/storage.js

@@ -327,6 +327,22 @@ function isAllowedStorageUrl(candidate, origins, hostBase, root) {
 //   3. le nombre de sauts est borné, et le protocole ne peut pas changer de nature : une
 //      redirection vers `file:` transformerait un amont distant en lecture de disque local.
 const MAX_REDIRECTIONS = 5;
+/**
+ * ⚠️ LE BUDGET EST GLOBAL À L'OPÉRATION, PAS PAR SAUT — ET IL ÉTAIT PAR SAUT.
+ *
+ * Chaque tour de boucle créait son propre `AbortSignal.timeout(60 s)`. Avec six tours (saut 0 à 5),
+ * une chaîne de redirections lente pouvait donc immobiliser la requête, sa socket et sa place
+ * d'admission pendant SIX MINUTES — alors que le commentaire juste en dessous affirmait « le délai
+ * est large mais il est borné ». Il bornait un saut ; personne ne bornait l'opération. Relevé par
+ * un audit externe le 12/09.
+ *
+ * ⚠️ CE N'EST PAS UN TROU DE SÉCURITÉ, ET LE DIRE COMPTE : chaque saut repasse la garde complète
+ * d'origine et recalcule le secret. Le risque est de DISPONIBILITÉ — c'est la même leçon que les
+ * appels non bornés du contexte autonome, au même endroit du raisonnement.
+ *
+ * Un seul signal, créé avant la boucle et partagé par tous les sauts : le total ne peut pas dépasser
+ * ce chiffre, quel que soit le nombre de redirections.
+ */
 const DELAI_MAX_MS = 60_000;
 
 async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root, secret } = {}) {
@@ -335,6 +351,10 @@ async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root,
   if (local) return readLocal(local, range);
 
   let cible = String(url);
+  // ⚠️ CRÉÉ ICI, PAS DANS LA BOUCLE : `AbortSignal.timeout` compte à partir de sa création, donc un
+  // signal fabriqué avant le premier saut EST le budget de toute l'opération.
+  const budget = (typeof AbortSignal !== "undefined" && AbortSignal.timeout)
+    ? AbortSignal.timeout(DELAI_MAX_MS) : undefined;
   for (let saut = 0; saut <= MAX_REDIRECTIONS; saut++) {
     const headers = { "accept-encoding": "identity" };
     if (range) headers.range = range;
@@ -342,8 +362,9 @@ async function fetchAllowedFile(url, { range } = {}, { origins, hostBase, root,
     if (isHostFetchUrl(cible, hostBase) && secret) headers["x-player-fetch-secret"] = secret;
 
     // Un amont qui ne répond jamais immobiliserait la requête et ses ressources indéfiniment.
-    // Le délai est large — un gros document met du temps — mais il est borné.
-    const r = await fetch(cible, { headers, redirect: "manual", signal: AbortSignal.timeout(DELAI_MAX_MS) });
+    // Le délai est large — un gros document met du temps — mais il borne l'OPÉRATION ENTIÈRE, pas
+    // chaque saut : le même signal sert à tous, donc le temps déjà consommé ne se reconstitue pas.
+    const r = await fetch(cible, { headers, redirect: "manual", ...(budget ? { signal: budget } : {}) });
     if (r.status < 300 || r.status > 399) return r;
 
     const suivante = r.headers.get("location");

package/docs/HOST-CONTRACT.md

@@ -441,10 +441,25 @@ Two deliberate exceptions, both written next to the code:
   with a shared counter would make the guard pay the price we had just spared the thing it guards.
   On that path the real protection is the cache, not the counter.
 
-⚠️ **The shared count is not atomic.** PostgREST cannot express "increment": it is a read then a
-write. Two instances can read the same value and write one. The counter therefore **under**-estimates
-under heavy concurrency — it lets a little more through, never refuses wrongly. Said plainly rather
-than implying a precision we do not have.
+⚠️ **The paragraph that used to stand here said the shared count was not atomic. That has been
+false since `0004`, and it contradicted the paragraph above it in this same document.** It was
+written before the database function existed and outlived what it described. An external audit found
+it on 2026-09-11; it is corrected rather than quietly deleted, because a host who read it may have
+built a compensating control they do not need.
+
+Here is the matrix, stated once, so nothing has to be inferred:
+
+| Installed | What actually protects you |
+|---|---|
+| `0003` **and** `0004` | fast local refusal **+ shared atomic counter** — the limit means what it says for the instance |
+| `0003` without `0004` | **local only.** The function is absent, PostgREST answers 404, and the shared stage lets through after warning by name |
+| neither | **local only**, in memory, warned by name |
+| keys prefixed `pread:` | local only, **deliberately** — see the exception above |
+
+⚠️ **Read the second row carefully: without `0004` the shared stage does not count less well, it
+does not count at all.** The degradation is to the local counter, not to a weaker shared one. The
+warning the player emits used to say *"non-atomic rate counters"*, which named a mode that does not
+exist; it now says the shared counter is unavailable.
 
 ## The three things a host implements
 
@@ -793,7 +808,10 @@ claimed the opposite. Two consequences you must act on:
 - **`bot-tts` now requires a `sessionId`**, bound to the requested `slug`, and the text must match
   something the assistant said in that session. The player reads `listMessages(sessionId)` and
   treats a message as the assistant's when its `role` is `bot`, `assistant` or `ai`, taking the text
-  from `text` or `content`. **Anything it cannot read counts as "not said"** — an unrecognised shape
+  from `text`, `content` or `body` — the same three fields, in the same order, as everywhere else in
+  this document. ⚠️ **This sentence named only the first two**, and an external audit found the
+  mismatch on 2026-09-11: a host whose messages carry `body` and nothing else would have read here
+  that its assistant never speaks, while the code reads it perfectly well. **Anything it cannot read counts as "not said"** — an unrecognised shape
   yields an empty set and every request is refused. On the one route that spends money, *"I could
   not verify"* must read as **no**, never as *go ahead*.
 
@@ -807,6 +825,75 @@ was a correct `bot`, and the reader would have returned an empty string for ever
 set, so every request refused, on a perfectly correct integration. If your field is none of those
 three, tell us and we widen the list. The field name carries no security; the **role** filter does.
 
+⚠️ **`reshare` now answers with a three-state `delivery`, and the state you must handle is
+`"unknown"`.** The response used to carry a single `sent` boolean, which collapsed three different
+outcomes: your mail path declined, *we* declined, or **the call failed without us learning what your
+side did**. Only the third is dangerous — if your host really sent the message and then answered too
+late, a caller reading `sent: false` retries, creating a **second child link and a second email**.
+
+| `delivery` | what happened | what to do |
+|---|---|---|
+| `"sent"` | your mail path reported success | nothing |
+| `"refused"` | a decision was made — yours or ours; `sendRefused` names it | surface the reason; retrying will refuse again |
+| `"unknown"` | the call failed (timeout, network). **We do not know whether the mail went out** | surface it to a human. **Do not retry automatically** — a retry may duplicate the email |
+| `"not-requested"` | `send` was falsy | nothing |
+
+`sent` is unchanged for integrations already reading it.
+
+⚠️ **And you can now make the retry safe: pass a `clientKey`.** Two `reshare` calls with the same
+parent, the same recipient and the same `clientKey` return the **same child link** and send **one**
+email — the second answers `delivery: "idempotent"`, which means *"this was already done"*, not
+*"this failed"*. Generate the key before the first call and reuse it on every retry.
+
+- The key you send is **fingerprinted on our side**, together with the parent and the recipient. It
+  is never stored as you wrote it, and it cannot collide with the system links the host-to-host path
+  creates.
+- ⚠️ **This rides on migration `0011`, which you may already have.** No new column was added: the
+  table has carried a unique idempotency key since then, and the reshare route had simply never been
+  offered it. If `0011` is not applied, `clientKey` is ignored and you get the old behaviour — a
+  retry creates a second link. Nothing breaks; the guarantee is what degrades, and `delivery` still
+  tells you when you are in doubt.
+- Without a `clientKey`, nothing changes: several links to the same recipient remain possible, which
+  is a legitimate thing to want.
+
+⚠️ **Avatars are only loaded from origins the page already serves content from, and everything else
+degrades to initials.** An avatar URL is an `<img>` in the browser of **every other viewer**: an
+arbitrary URL therefore sends each of them — their IP, user agent, the time, the page origin — to
+whoever wrote it. That is not an XSS (the markup is escaped); it is a privacy leak aimed at your
+audience, and an external audit reproduced it on 2026-09-12 against the real chat renderer.
+
+Three things changed, and the second one is the one you may notice:
+
+- **A participant who is not authenticated no longer supplies an avatar at all.** A proven identity
+  replaces what is asserted; an anonymous visitor proves nothing, so the field is dropped and the
+  audience sees initials.
+- **A member's avatar must come from your Supabase origin (or be a relative URL).** It arrives from
+  your identity provider's metadata, and a provider that lets a user edit that field would hand us
+  an arbitrary URL under a proven name. ⚠️ **If your members' avatars live elsewhere — Gravatar, a
+  CDN, Google — they will now render as initials.** Serve them from your own storage to get the
+  images back. The degradation is visible and reversible; the leak was neither.
+- **The renderer refuses the same URLs again**, because one path never reaches this server: a
+  participant can broadcast presence over Realtime straight to the other viewers. No server-side
+  barrier can see that, so the check also lives where every path converges — at render time.
+
+⚠️ **What your `storage.remove` returns now decides whether a row survives.** It returns a boolean:
+`true` means the object is gone, `false` means it is still there. Until 0.1.163 the retention sweep
+erased the row either way — and since this capability exposes `put` and `remove` but **never
+`list`**, the row is the only path to the object: erasing it stranded the file in the bucket
+permanently. The sweep now **keeps the row** when `remove` returns `false`, and reports it as
+`retenues`. Two consequences for you:
+
+- **Do not return `false` for an object that was already absent.** An already-gone object is a
+  success for this purpose — returning `false` makes the sweep retain a row forever, waiting for a
+  file that does not exist. ⚠️ **The player's own standalone context used to have exactly this bug**,
+  found while writing this paragraph: it returned `r.ok`, and Supabase Storage answers an error for a
+  missing object, so the fix for lost files would have created permanent retention instead. It now
+  treats 404 — and a body naming "not found" — as removed, because what is being asked is *"the
+  object is no longer there"*, and it is not there. If you wrap a different provider, do the same.
+- **`retenues > 0` in a retention report means your provider refused a removal**, not that the purge
+  is broken. The next pass retries. A row that lingers is recoverable; a file whose only pointer was
+  erased is not.
+
 **If you write to the `tts-cache` bucket yourself, write the trace too.** Retention removes an object
 only when its fingerprint has a row in `doc_tts_objects`, and only the player's own route writes that
 row. Anything your code puts in that bucket is therefore invisible to the sweep — **permanently**,

package/docs/RETENTION.md

@@ -131,8 +131,11 @@ it is the trace. The row records a fingerprint and a date and nothing else: writ
 would recreate, inside the database, whatever personal data the bucket may already hold — and make
 it queryable, which is strictly worse than not having it.
 
-⚠️ **A visitor chooses what goes in.** `bot-tts` accepts the caller's text, so a unique text leaves
-an MP3 and a JSON in a public bucket. The grouping and ceilings added in 0.1.140 bound the cost per
+⚠️ **This paragraph used to say a visitor chooses what goes in. That stopped being true** when
+`bot-tts` began confronting the text with what the assistant actually said in that session — an
+external audit found the stale claim on 2026-09-11. The caller **proposes** a text; only a text the
+assistant already spoke is accepted. What still holds is the consequence: each *distinct accepted*
+text leaves an MP3 and a JSON in a public bucket. The grouping and ceilings added in 0.1.140 bound the cost per
 hour; only this window bounds the **duration**.
 
 ## Purging the reader IP and User-Agent (migrations 0026 and 0027)
@@ -284,8 +287,54 @@ numbers, say so; do not round the sentence.
 it defers nothing. A host with no PITR and eight daily snapshots has **one** deadline, not two: the
 age of its oldest snapshot. Take the later of the deadlines that *exist*.
 
+## Cleaning up the objects the broken sweep stranded
+
+The voice-cache sweep removed nothing until it was fixed (see above), so every voice object it
+"purged" is still in the bucket with its row deleted — unreachable by the product, by construction.
+`tools/orphelins-tts.mjs` exists for exactly that backlog, and for nothing else.
+
+```
+node tools/orphelins-tts.mjs --inspecter [--age-jours=N] [--limite=N]
+node tools/orphelins-tts.mjs --inspecter --supprimer --confirme=<the count from the report>
+```
+
+It reads `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` from the environment, and it deliberately
+**steps outside the host contract**: it talks to the Storage API directly to do the one thing the
+contract does not expose — `list`. That is why it is not a guard, runs in no workflow, and contacts
+nothing at all until you pass `--inspecter`.
+
+⚠️ **It cannot tell our orphans from yours, and no measurement can.** An object with no row is one of
+three things: stranded by the broken sweep, a relic from before migration 0021, or **a file your own
+code wrote under the player's naming** — one integrating host reported 908 of those. The tool
+therefore:
+
+- **reports by default** and deletes nothing;
+- treats only objects **older than the retention window** as candidates — a recent object with no row
+  may be a synthesis whose trace write just failed, and deleting it would erase a file the product is
+  about to serve;
+- refuses to act unless you **type the candidate count back** from a report it produced on the
+  current state. If the number has changed since you looked, the bucket moved, and that is precisely
+  what the barrier is there to tell you;
+- never touches a name that is not `<fingerprint>.mp3` / `.json`, nor an object whose date it cannot
+  read — no date means *we do not know*, and we do not delete what we do not know.
+
+Read the report before passing `--supprimer`. If your own code writes to this bucket, write the trace
+too (see *Voice* in `docs/HOST-CONTRACT.md`) — that is what makes your objects distinguishable, and
+what keeps them out of this tool's candidate list.
+
 ## Limits stated rather than left unsaid
 
+- ⚠️ **Until the next release the voice-cache sweep removed nothing at all, in the reference host context,
+  and the paragraph below is what hid it.** `storage.remove` carries an allow-list — a last barrier
+  before a DELETE with the service-role key — and it named only `present-attachments`. `tts-cache`
+  was refused **before any network call**: every removal returned `false`, the trace row was erased
+  anyway, and the object stayed in a public bucket with no path left to it. That is precisely the
+  harm migration 0021 was written to make repairable, realised at 100%.
+  ⚠️ **What concealed it is a true explanation.** Those refusals were counted in `fichiersErreur`,
+  which the next bullet attributes — correctly — to alignment files that legitimately do not exist.
+  A correct account of the noise is the best place to hide a signal. Found on 2026-09-12 while
+  writing the documentation for a *different* fix on the same path; the allow-list now names both
+  buckets the sweep must reach, and nothing else.
 - ⚠️ **`fichiersErreur` can be high without any removal having failed.** Each fingerprint has two
   objects, and the alignment `.json` is not always there — the provider does not always return one.
   Measured on an integrating host's bucket on 27/08: **552 `.mp3` for 356 `.json`**, so 196 audio
@@ -309,6 +358,28 @@ age of its oldest snapshot. Take the later of the deadlines that *exist*.
 - **The dryRun report is complete for presentations**: `messagesExaminees`, `presencesExaminees`
   and `fichiersCandidats` say what the REAL purge would do — same selection walk, no-op deletion,
   `efface.* = 0`.
+- ⚠️ **A row is never erased above a file that resisted, and `retenues` counts the rows kept.**
+  Until 0.1.163 the deletion was unconditional: a failed `storage.remove` still erased the row — and
+  with it the only path to the object. The `storage` capability exposes `put` and `remove`, **never
+  `list`**, which is the very argument that justified migration 0021: with no row there is nothing
+  to walk, so the object stays in the bucket **permanently**, beyond the reach of any sweep. Found
+  by an external audit on 2026-09-12, reproduced before being fixed. A retained row is recoverable —
+  the next pass retries it; a lost file is not. Read `retenues > 0` as *"the storage provider refused
+  a removal; look at it"*, not as a purge failure.
+- ⚠️ **The alignment `.json` never retains anything — only the audio does.** A third of fingerprints
+  legitimately have no companion (see the 552/356 measurement above); gating the row on both objects
+  would hold a third of the cache forever to protect files that do not exist. So the `.mp3` alone
+  decides, and a missing `.json` is still **counted** in `fichiersErreur` rather than masked.
+- ⚠️ **A presentation is not deleted above a retained message.** The condition used to require only
+  that nothing was `tronque`; "retained" is a second way of not having gone, and without it the fix
+  above would have reopened the parent/child orphan an earlier audit had closed.
+- ⚠️ **The delete carries the purge predicate, not just the identifiers.** The sweep selects by date
+  and used to delete by identifier alone: a heartbeat landing between the two requests refreshed a
+  row that was then erased anyway, judged on a date that was no longer its own. Same audit, same
+  day, also reproduced. PostgREST applies every predicate in the URL at delete time, so replaying
+  the original filter makes the row be judged on its state **at that instant**. The race window does
+  not disappear — it stops being destructive. `select=` returns only what actually went, so the
+  counts stay honest when the database spares a row at the last moment.
 - **The purge advances in BOUNDED BATCHES** (200 rows, a ceiling of 5000 per table and 500
   presentations per run): it selects a batch of identifiers, deletes them with `id=in.(…)`, and
   starts again. The report (`r.rapport`) carries, per table: `examinees`, `supprimees`, `tronque`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.162",
+  "version": "0.1.164",
   "description": "Self-hosted document viewer: per-recipient tracked links, reading analytics, live presentation. The core knows nothing about the application hosting it — everything it borrows arrives through an injected context.",
   "keywords": [
     "pdf-viewer",