discovery-media-player 0.1.150 → 0.1.152

package/context/standalone.js

@@ -45,7 +45,13 @@ function creerDb(env) {
   const url = sansBarreFinale(env.SUPABASE_URL);
   const cle = String(env.SUPABASE_SERVICE_ROLE_KEY || "");
 
-  async function request(chemin, options = {}) {
+  // ⚠️ UN SEUL ENDROIT QUI APPELLE ET QUI REJETTE. `count` a besoin d'un EN-TÊTE de la réponse,
+  // pas de son corps ; le tenter avec son propre `fetch` aurait recopié la construction des
+  // en-têtes, l'abandon, et surtout la forme de l'erreur (`statusCode`/`details`) dont six sites
+  // appelants dépendent. Une seconde orthographe de « appeler PostgREST et rejeter correctement »
+  // est exactement la recopie que ce dépôt a déjà payée trois fois. `request` et `count` se
+  // partagent donc l'appel ; ils ne se partagent que ce qu'ils lisent de la réponse.
+  async function appel(chemin, options = {}) {
     if (!url || !cle) {
       // Message explicite plutôt que `undefined` plus loin : sans base, ce sont les liens tracés
       // et les présentations qui sont indisponibles — pas l'affichage d'un document.
@@ -92,10 +98,47 @@ function creerDb(env) {
       try { erreur.details = JSON.parse(detail); } catch { /* corps non JSON : le message suffit */ }
       throw erreur;
     }
+    return r;
+  }
+
+  async function request(chemin, options = {}) {
+    const r = await appel(chemin, options);
     const texte = await r.text();
     return texte ? JSON.parse(texte) : null;
   }
 
+  /**
+   * ⚠️ LE COMPTE EXACT, ET C'EST UNE QUESTION — PAS UN MÉCANISME. Le contrat demande « combien de
+   * lignes ce chemin sélectionne-t-il ? » ; il ne demande pas de lire un en-tête. Un hôte sur une
+   * autre base répond par un `count(*)`, celui-ci par PostgREST. Nommer le mécanisme dans le
+   * contrat l'aurait rendu PostgREST-seulement, ce que la règle de portabilité refuse.
+   *
+   * ⚠️ POURQUOI IL EXISTE : le comptage par LIGNES dépend des plafonds de qui les rend. PostgREST a
+   * `db-max-rows`, réglé à 1000 par défaut chez Supabase, et un hôte a mesuré une table de 1651
+   * lignes rendue « 1000 ». Le compte d'en-tête, lui, n'a AUCUN plafond à deviner et ne transporte
+   * rien. Mesuré chez un hôte le 02/09 : `Prefer: count=exact` + `Range: 0-0` rend bien le compte
+   * exact ; l'autre voie envisagée, `?select=count()`, est morte — `db-aggregates-enabled` vaut
+   * `false` par défaut, vérifié sur deux projets distincts.
+   *
+   * ⚠️ ET UN GET PLUTÔT QU'UN HEAD, DÉLIBÉRÉMENT. Un HEAD ne rend aucun corps, donc aucune erreur
+   * ANALYSÉE : l'appelant ne pourrait plus distinguer « colonne supprimée » (42703, un état connu
+   * qui vaut zéro) d'une panne. `Range: 0-0` ne coûte qu'une ligne et garde l'erreur lisible.
+   *
+   * ⚠️ RENDRE `null` PLUTÔT QUE ZÉRO QUAND LE COMPTE MANQUE. PostgREST écrit `…/*` quand il ne
+   * compte pas. Zéro est la réponse qui autorise à supprimer une colonne : la fabriquer depuis une
+   * réponse qui ne compte pas serait le pire mensonge que cette capacité puisse faire.
+   */
+  async function count(chemin, options = {}) {
+    const r = await appel(chemin, {
+      ...options,
+      method: "GET",
+      headers: { ...(options.headers || {}), Prefer: "count=exact", Range: "0-0" },
+    });
+    // `Content-Range: 0-0/1651` — le total suit la barre. `…/*` veut dire « je n'ai pas compté ».
+    const trouve = /\/(\d+)\s*$/.exec(String(r.headers.get("content-range") || ""));
+    return trouve ? Number(trouve[1]) : null;
+  }
+
   /** Lecture paginée complète : un document très partagé dépasse la pagination par défaut. */
   async function selectAll(chemin, taille = 1000) {
     const tout = [];
@@ -107,7 +150,7 @@ function creerDb(env) {
     }
   }
 
-  return { request, selectAll, configuree: !!(url && cle) };
+  return { request, selectAll, count, configuree: !!(url && cle) };
 }
 
 /**
@@ -356,7 +399,7 @@ function createStandaloneContext(env = process.env) {
       },
     },
 
-    db: { request: db.request, selectAll: db.selectAll },
+    db: { request: db.request, selectAll: db.selectAll, count: db.count },
 
     // Sans expéditeur configuré, le re-partage et le code du mur d'accès sont indisponibles — et
     // le disent. Ils ne prétendent pas avoir envoyé.

package/docs/HOST-CONTRACT.md

@@ -487,7 +487,7 @@ above: an unheard-of action answered *no* narrows this view rather than breaking
 gains a `purge` block counting the rows that still carry a reader IP or a raw User-Agent:
 
     "purge": { "borne": 5000, "tronque": false, "lignes": { "sessions": 1908, "vues": 3200 },
-               "sessionsIp": 0, "sessionsUa": 0, "vuesUa": 0, "vide": true }
+               "sessionsIp": 0, "sessionsUa": 0, "vuesUa": 0, "vide": true, "voie": "bornee" }
 
 `vide` is the reading that matters: `true` means nothing of that legacy is left **on this
 instance's live rows** — the condition under which those columns can eventually be dropped —
@@ -522,6 +522,58 @@ by the response body alone. Reading the count from `Content-Range` under `Prefer
 no ceiling to guess and transports nothing; it is strictly better, and it needs the `db` capability
 to expose response headers, which today it does not.
 
+⚠️ **`db.count(path)` is the seam that closes this, and it is optional.** ⚠️ **The standalone
+context shipped in this package already implements it** — if you build your context from
+`discovery-media-player/context/standalone`, you get it on your next upgrade and there is nothing
+to decide or write. This section is for a host that implements the `db` capability itself. A host
+asked which of the two it was, and the answer was missing from this page: *"the two look alike in
+your code and not at all alike at your hosts."* If your `db` capability
+exposes it, the player asks it first and publishes an **exact** count — no bound, no `tronque`, and
+no rows transported at all. If it is absent, everything above still applies unchanged: the bounded
+read with its cursor probe. **That fallback is the whole design.** Third-party hosts implement this
+capability themselves, and requiring a new method would break every one of them; the only kind of
+contract addition this repository allows is the kind whose absence is the previous behaviour.
+
+    db.count(path) → number | null
+
+**It asks the question, not the mechanism.** *How many rows does this path select?* — not *read this
+header*. A PostgREST host answers with `Prefer: count=exact`; a host on another database answers
+with a `count(*)`. Naming the header in the contract would have made it PostgREST-only, which the
+portability rule refuses.
+
+⚠️ **Answer `null` when you cannot say — never `0`.** Zero is the answer that authorises dropping a
+column. Anything that is not a non-negative integer (a string, a float, `undefined`, `NaN`) is read
+as "no answer" and the player falls back rather than believing it.
+
+⚠️ **And `voie` tells you which route produced the numbers, because the numbers cannot.** `"exact"`,
+`"bornee"`, or `"mixte"` when both served the same read — which happens for real: a host mid-purge
+whose column is already dropped makes `count` throw on the filtered paths and answer on the same
+table's totals.
+
+This field exists because two hosts, independently and on the same day, found they could not verify
+their own seam. An exact count and an untruncated bounded count render an **identical** block —
+same numbers, same `tronque`, same `vide`. So a `db.count` that returns a string, or a float, falls
+back **silently** and the card looks exactly like a working one: you believe your seam is wired
+when it is not. One host caught it only by luck of volume — their table held 1655 rows, and the
+bounded route is structurally incapable of exceeding the 1000-row ceiling, so the number itself
+happened to be proof. Under a thousand rows there is no such luck, and the other host, whose
+volumes are small, could not tell at all.
+
+**Check `voie`, not a value.** A control that distinguishes two *mechanisms* must rest on something
+one can do and the other cannot; a value both could return proves nothing, and a value written down
+from yesterday's measurement rots without anyone touching anything.
+
+⚠️ **The two alternatives were measured at a host, not assumed here** — recorded so nobody proposes
+them again in six months believing they were never tried. **`?select=count()` is dead**:
+`db-aggregates-enabled` is `false` by default, verified on two distinct Supabase projects, and the
+measurement is solid for a reason worth stating — the `PGRST123` error arrives *before* the
+permission check, where the same table queried without an aggregate answers `42501 permission
+denied`. The answer therefore depends on neither grants nor any `revoke`: it is a property of the
+**configuration**, not of authorization. That was the route we would have preferred, since it bound
+no one to a contract. **`Prefer: count=exact` with `Range: 0-0` works**: the exact count travels in
+the header and the body carries nothing. It is the only one of the two that exists, and its only
+obstacle is this contract.
+
 ⚠️ **And the same ceiling applies to every read you make through your own client, not just to
 ours.** `limit=20000` does not return twenty thousand rows: PostgREST caps the response at
 `db-max-rows` — **1000** on a default Supabase project — and says so nowhere in the body. A read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.150",
+  "version": "0.1.152",
   "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",
@@ -67,7 +67,7 @@
     "build": "node -e \"require('fs').existsSync('build/bundle.mjs')||(console.error('Ce script ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && node build/bundle.mjs && tsc -p tsconfig.build.json && node -e \"import('./build/bundle.mjs').then(m=>m.marquerDistEsm())\"",
     "test": "node -e \"require('fs').existsSync('server/__tests__')||(console.error('Ce banc ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && vitest run",
     "test:watch": "vitest",
-    "lint": "node -e \"require('fs').existsSync('eslint.config.mjs')||(console.error('Ce script ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && eslint bin context server src build tools charge --max-warnings 0",
+    "lint": "node -e \"require('fs').existsSync('eslint.config.mjs')||(console.error('Ce script ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && eslint bin context server src build tools charge base --max-warnings 0",
     "lint:fix": "eslint bin context server src build tools charge --fix",
     "typecheck": "node -e \"require('fs').existsSync('tsconfig.json')||(console.error('Ce script ne vit pas dans le paquet publié - le champ scripts annonce plus que le tarball ne contient. Clonez le depot puis npm ci : https://github.com/Juli1artha/discovery-media-player'),process.exit(1))\" && tsc --noEmit",
     "prepublishOnly": "npm run build && npm test",

package/server/mesures.js

@@ -130,6 +130,12 @@ function observerBase(db) {
   vu.__mesuree = true;
   vu.request = mesurer("request");
   if (typeof db.selectAll === "function") vu.selectAll = mesurer("selectAll");
+  // ⚠️ CHAQUE MÉTHODE AJOUTÉE À LA CAPACITÉ DOIT ÊTRE AJOUTÉE ICI, et l'héritage rend cet oubli
+  // SILENCIEUX : `Object.create` laisse passer une méthode nouvelle, vivante et non mesurée — donc
+  // le paragraphe ci-dessus, qui promet de couvrir « y compris ce que personne n'a encore écrit »,
+  // deviendrait faux sans que rien ne rougisse. `count` est optionnelle chez l'hôte ; quand elle
+  // existe, elle interroge la base et son temps compte comme le reste.
+  if (typeof db.count === "function") vu.count = mesurer("count");
   return vu;
 }
 

package/server/retention.js

@@ -477,8 +477,21 @@ const TABLES_RESTE = [["sessions", "commercial_doc_sessions", "session_id"],
  */
 const COLONNE_ABSENTE = "42703";
 
-/** `{ n, tronque }` — `n` nul veut dire indéterminé, jamais zéro. */
-const compte = (n, tronque) => ({ n, tronque });
+/**
+ * `{ n, tronque, voie }` — `n` nul veut dire indéterminé, jamais zéro.
+ *
+ * ⚠️ ET `voie` NOMME LE MÉCANISME QUI A PRODUIT LE NOMBRE, parce que le nombre seul ne le dit pas.
+ * Un compte exact et un compte borné NON tronqué rendent le même JSON : deux hôtes l'ont relevé le
+ * même jour, l'un en constatant qu'il ne pouvait pas vérifier sa propre couture, l'autre en
+ * écrivant un contrôle qui n'a marché que par chance de volume — sa table dépassait mille, donc la
+ * voie par lignes était structurellement incapable de rendre son chiffre. Sous mille, personne ne
+ * peut trancher, et un `db.count` qui rend une chaîne retombe SILENCIEUSEMENT sur la voie bornée :
+ * l'hôte croit sa couture branchée alors qu'elle ne sert pas.
+ */
+const compte = (n, tronque, voie) => ({ n, tronque, voie });
+
+const VOIE_EXACTE = "exact";
+const VOIE_BORNEE = "bornee";
 
 /**
  * ⚠️ « MOINS QUE DEMANDÉ » NE PROUVE PAS LA FIN — ET C'EST UN HÔTE RÉEL QUI L'A MONTRÉ.
@@ -510,6 +523,20 @@ const compte = (n, tronque) => ({ n, tronque });
  * le compte d'en-tête (`Content-Range` sous `Prefer: count=exact`) lui est strictement supérieur :
  * il ne dépend d'aucun plafond. Il demanderait d'élargir la capacité `db` du contrat d'hôte, qui ne
  * rend aujourd'hui que le corps analysé.
+ *
+ * ⚠️ LES DEUX AUTRES VOIES ONT ÉTÉ MESURÉES CHEZ UN HÔTE, PAS SUPPOSÉES ICI. On les note pour que
+ * personne ne les repropose dans six mois en croyant qu'elles n'ont jamais été essayées :
+ *
+ *   `?select=count()` — MORT. `db-aggregates-enabled` vaut `false` par défaut, vérifié sur DEUX
+ *   projets Supabase distincts. Et la mesure est solide pour une raison qui vaut d'être dite :
+ *   l'erreur `PGRST123` arrive AVANT le contrôle de droits — la même table, interrogée sans
+ *   agrégat, rend `42501 permission denied`. La réponse ne dépend donc ni des droits ni d'un
+ *   `revoke` : c'est une propriété de la CONFIGURATION, pas de l'autorisation. C'était la voie
+ *   qu'on aurait préférée, puisqu'elle n'engageait aucun contrat.
+ *
+ *   `Prefer: count=exact` + `Range: 0-0` — MARCHE. Le compte exact voyage dans l'en-tête, le corps
+ *   ne transporte rien. C'est donc la SEULE des deux qui existe, et son seul obstacle est le
+ *   contrat d'hôte.
  */
 async function resteApres(chemin, cle, dernier) {
   // Sans curseur lisible, la fin ne se prouve pas : « au moins » est le seul côté sûr.
@@ -523,23 +550,64 @@ async function resteApres(chemin, cle, dernier) {
   } catch { return true; }
 }
 
+/**
+ * ⚠️ LA VOIE EXACTE, QUAND L'HÔTE LA FOURNIT — ET LE CONTRAT DEMANDE LA QUESTION, PAS LE MÉCANISME.
+ * `db.count(chemin)` rend « combien de lignes ce chemin sélectionne-t-il ». Un hôte PostgREST y
+ * répond par `Prefer: count=exact` ; un hôte sur une autre base par un `count(*)`. Nommer l'en-tête
+ * dans le contrat l'aurait rendu PostgREST-seulement, ce que la règle de portabilité refuse.
+ *
+ * ⚠️ ELLE EST OPTIONNELLE, ET SON ABSENCE N'EST PAS UNE PANNE. Des hôtes tiers implémentent la
+ * capacité `db` eux-mêmes ; exiger une méthode nouvelle les casserait tous. Absente, on retombe sur
+ * le comptage borné ci-dessous, qui reste juste — seulement moins précis. C'est la seule forme
+ * d'ajout au contrat que ce dépôt s'autorise : celle dont le repli est le comportement d'avant.
+ *
+ * ⚠️ ET TOUT CE QUI N'EST PAS UN ENTIER POSITIF RETOMBE, plutôt que d'être cru. Un hôte qui rend
+ * `undefined`, une chaîne, ou un négatif n'a pas répondu à la question — le lire comme un compte
+ * fabriquerait le chiffre que ce fichier existe pour ne pas fabriquer.
+ */
+async function compteExact(chemin) {
+  // ⚠️ SORTIE ANTICIPÉE, PAS GARDE — ET LA DISTINCTION EST MESURÉE. Le `catch` ci-dessous suffirait
+  // à la correction : appeler une méthode absente lève, on retombe, le résultat est le même. Muté
+  // en `if (!PLAYER.db)`, AUCUN banc ne rougit — c'est dit ici plutôt que laissé croire à une
+  // protection. Ce que cette ligne achète est un COÛT : sans elle, tout hôte qui n'implémente pas
+  // `count` construirait cinq exceptions à chaque lecture de carte, pour rien.
+  if (!PLAYER.db || typeof PLAYER.db.count !== "function") return null;
+  try {
+    const n = await PLAYER.db.count(chemin);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+  } catch {
+    // ⚠️ ON NE RECOPIE PAS ICI LA RÈGLE DE LA COLONNE ABSENTE. Une première rédaction traitait le
+    // `42703` sur cette voie aussi, pour rendre zéro « comme l'autre ». Muté, ce branchement n'a
+    // fait rougir aucun banc — et pour une raison de fond, pas par manque de cas : une colonne
+    // supprimée fait échouer LES DEUX voies de la même façon, donc le repli rend déjà ce zéro. Le
+    // branchement n'ajoutait rien d'observable et créait un SECOND endroit où tenir la même règle.
+    return null;   // on ne sait pas ⇒ on essaie l'autre voie, qui elle sait lire le 42703
+  }
+}
+
 async function compterBorne(chemin, cle) {
+  // ⚠️ UN COMPTE EXACT N'EST NI BORNÉ NI TRONQUÉ, quelle que soit sa taille : `borne` décrit la
+  // méthode par lignes, pas celle-ci. `tronque: false` garde donc le sens qu'il a partout —
+  // « lisez ce nombre comme exact » — au lieu d'en prendre un second selon la voie employée.
+  const exact = await compteExact(chemin);
+  if (exact !== null) return compte(exact, false, VOIE_EXACTE);
   try {
     // ⚠️ BORNE + 1 : la ligne excédentaire ne sert qu'à PROUVER qu'il en reste. On ne la publie pas.
     // ⚠️ ET L'ORDRE N'EST PAS DÉCORATIF : sans lui, « la dernière ligne reçue » ne désigne aucune
     // frontière, et le curseur de la sonde ne voudrait rien dire.
     const lignes = await PLAYER.db.request(
       `${chemin}&order=${cle}.asc&limit=${BORNE_RESTE + 1}`, { timeoutMs: 8000 });
-    if (!Array.isArray(lignes)) return compte(null, false);
+    if (!Array.isArray(lignes)) return compte(null, false, VOIE_BORNEE);
     // Notre propre borne atteinte : la preuve est dans la ligne excédentaire, rien à demander.
-    if (lignes.length > BORNE_RESTE) return compte(BORNE_RESTE, true);
+    if (lignes.length > BORNE_RESTE) return compte(BORNE_RESTE, true, VOIE_BORNEE);
     // Zéro ligne : la sonde au-delà rendrait zéro elle aussi et n'apprendrait rien — y compris sous
     // un plafond à zéro, que ni l'une ni l'autre ne distingue d'une table vide.
-    if (!lignes.length) return compte(0, false);
-    return compte(lignes.length, await resteApres(chemin, cle, lignes[lignes.length - 1][cle]));
+    if (!lignes.length) return compte(0, false, VOIE_BORNEE);
+    return compte(lignes.length, await resteApres(chemin, cle, lignes[lignes.length - 1][cle]),
+      VOIE_BORNEE);
   } catch (e) {
-    if (e && e.details && e.details.code === COLONNE_ABSENTE) return compte(0, false);
-    return compte(null, false);   // indéterminé — surtout pas zéro
+    if (e && e.details && e.details.code === COLONNE_ABSENTE) return compte(0, false, VOIE_BORNEE);
+    return compte(null, false, VOIE_BORNEE);   // indéterminé — surtout pas zéro
   }
 }
 
@@ -582,6 +650,18 @@ async function resteDeLaPurge() {
   // confiance aux autres, alors que la borne est commune et que la question ne l'est pas.
   out.tronque = [...comptes, ...totaux].some((c) => c.tronque);
   out.lignes = parTable;
+  // ⚠️ UNE SEULE RÉPONSE POUR LES CINQ COMPTES, ET TROIS ÉTATS PLUTÔT QUE DEUX. La question qu'un
+  // hôte se pose est « ma couture sert-elle ? », pas « laquelle des cinq ». `"mixte"` n'est pas une
+  // commodité : il arrive vraiment — un `count` qui lève sur le chemin d'une colonne supprimée et
+  // répond sur le total de la même table — et c'est précisément le cas qu'un drapeau binaire
+  // aurait dû arrondir dans un sens ou dans l'autre, donc mentir.
+  //
+  // ⚠️ CE CHAMP NE DIT RIEN SUR LA JUSTESSE DES NOMBRES, seulement sur leur provenance. Il ne
+  // double aucun autre : `tronque` vaut `false` sur les DEUX voies, c'est même toute la raison
+  // d'être de cette ligne.
+  const voies = [...comptes, ...totaux].map((c) => c.voie);
+  out.voie = voies.every((v) => v === VOIE_EXACTE) ? VOIE_EXACTE
+    : voies.every((v) => v === VOIE_BORNEE) ? VOIE_BORNEE : "mixte";
   SONDES_RESTE.forEach(([nom], i) => { out[nom] = comptes[i].n; });
   // ⚠️ TROIS ÉTATS, PAS DEUX. `true` : plus rien, le retrait des colonnes est permis ICI. `false` :
   // il reste des lignes. `null` : au moins une sonde n'a pas répondu — on ne sait pas, et « on ne