discovery-media-player 0.1.151 → 0.1.153

package/docs/HOST-CONTRACT.md

@@ -50,7 +50,7 @@ need.
   "presenceDurcissement": "inconnu",
   "presenceFusion": "inconnu",
   "lectureSaturee": { "total": 0, "fenetreS": 0, "derniereIlYaS": null },
-  "mesures": { "fenetreS": 0, "seauxMs": [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000], "routes": {}, "base": { "n": 0 }, "statuts": { "ok": 0, "refus4xx": 0, "debit429": 0, "occupe503": 0, "erreur5xx": 0 }, "memoireMio": { "rss": 0, "heap": 0, "tampons": 0 }, "boucleMs": { "n": 0, "moyen": null, "p99": null, "resolutionMs": 20 } },
+  "mesures": { "fenetreS": 0, "seauxMs": [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000], "familles": ["document", "presentation", "action", "fichier", "carte", "autre"], "routes": {}, "base": { "n": 0 }, "statuts": { "ok": 0, "refus4xx": 0, "debit429": 0, "occupe503": 0, "erreur5xx": 0 }, "memoireMio": { "rss": 0, "heap": 0, "tampons": 0 }, "boucleMs": { "n": 0, "moyen": null, "p99": null, "resolutionMs": 20 } },
   "retentionSweep": false,
   "hostShare": true,
   "hostMail": true,
@@ -180,6 +180,7 @@ these numbers from their side.
 |---|---|
 | `fenetreS` | seconds this process has been running — **the window every total below was counted over** |
 | `seauxMs` | the bucket ladder the percentiles are read off, published **with** the numbers |
+| `familles` | **the denominator of `routes`** — every family this build measures, whether or not it was exercised. It does not move with traffic; that is what makes it a denominator |
 | `routes` | one entry per family of work — `document`, `presentation`, `action`, `fichier`, `carte`, `autre`. Families absent from the object were never exercised in this process |
 | `base` | the same shape, for calls through the `db` capability **you** supply — measured at the seam, so it covers every call, including ones nobody has written yet |
 | `statuts` | responses by class: `ok` (<400), `refus4xx`, `debit429`, `occupe503`, `erreur5xx` |
@@ -194,6 +195,17 @@ reading is. `null` means *past the top of the ladder* (over 10 s), which is itse
 ⚠️ **`n: 0` is not `0 ms`.** A family that was never exercised reports `{ "n": 0 }` and nothing
 else, and `boucleMs` with no samples reports `moyen: null` — not a zero that would read as *healthy*.
 
+⚠️ **`routes: {}` used to be indistinguishable from broken instrumentation, and `familles` is why
+it no longer is.** Omitting an unexercised family is correct — a `0 ms` would read as *instantaneous*
+— but the omission left a reader unable to tell *no traffic in this window* from *measurement is not
+running*. A loaded host never meets the question: its entries are always there, so their presence
+witnesses itself.
+
+The rule came from a host measuring their own smallness: **a field whose value is its own witness at
+scale needs an explicit witness at small scale.** At 99 sessions nothing witnesses anything, and a
+busier host is better instrumented without having instrumented anything. `statuts` and `boucleMs`
+already carried their denominators; `routes` had not.
+
 ⚠️ **`boucleMs` is the delay, not the interval.** The sampler observes how long its own timer
 actually took, which at rest equals its resolution; the resolution is subtracted, so an idle
 instance reports about `0` rather than a permanent `20` that would send you hunting a fault that
@@ -487,7 +499,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 —
@@ -545,6 +557,24 @@ portability rule refuses.
 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
@@ -863,6 +893,64 @@ cannot. Setting the number spares you that reasoning entirely.
 but *did you measure exactly what fails*. Two true statements about the same instance can describe
 different responses.
 
+## What you can see and we cannot
+
+**Read this only if you run this player somewhere.** If you are evaluating it, skip to Versioning —
+this section asks for nothing from you.
+
+⚠️ **Everything below exists because three defects in one week were found by hosts, not by us**, and
+none of the three was findable from here. Every guard here measures this repository. They
+cannot measure an installation they have never seen, and that is not a gap we can close by adding
+one more. So this is not a request for feedback in general — it is four specific questions we cannot
+answer ourselves, each printed with what it cost us not to have asked it earlier.
+
+You owe us none of this. But you are the only one who can answer any of it.
+
+**1. A ceiling in your installation that we assume away.** PostgREST's `db-max-rows` is set to 1000
+by default on Supabase: the server returns 1000 rows however many you ask for. We compared what we
+received against *our* bound, concluded "not truncated", and published `1000` rows of a 1651-row
+table **asserting the number was exact** — which is worse than the defect it replaced, because the
+previous version claimed nothing. Four hours after the release, a host measured it. If your
+deployment caps, times out, paginates, or rewrites anything between us and your database, that
+limit is invisible from here and our arithmetic is probably wrong about it.
+
+**2. Something this card asserts that you can check against your own database.** Not "does it look
+right" — *does this number match what a query returns right now*. The purge card is the obvious one:
+`vide: true` is what authorises dropping a column, so a wrong `true` is expensive and a wrong `0`
+authorises a deletion. A host who compared the card against their own tables is the reason the
+counter stopped being able to lie.
+
+**3. What your volumes hide from you — and what they reveal for free.** This one is the least
+obvious and cost us a field. At 1655 rows an exact count **is its own proof**: it exceeds a ceiling
+the bounded route structurally cannot cross, so the number itself witnesses which mechanism ran. At
+99 sessions no value can ever separate the two, and a broken seam is indistinguishable from a
+working one. Same code, same card — one installation detects a failure for free that the other
+cannot see at all. So: **tell us your orders of magnitude**, and tell us when a field of ours only
+makes sense at your scale. A small host is not merely short of occasions; it has lost discriminating
+power, and that is our problem to fix with an explicit witness, not theirs to live with.
+
+**4. A rule you drew from your own defect.** The most useful things we received this week were not
+bug reports. They were sentences: *a control that separates two mechanisms must rest on what one can
+do and the other cannot, never on a value both could return* — and *is there a state of the world
+where this value is false?*, which is the question separating a limit of observation from a silent
+failure mode. Both were written by hosts about their own mistakes. Both, applied to this repository
+within the hour, found something. A defect tells us about one line; a rule tells us where to look.
+
+⚠️ **And tell us what you did not do.** A host closed a report with thirty-two reads still
+unaudited, said so plainly, and that sentence is the only reason we know those reads exist. We
+cannot measure your code. We can only know what someone wrote down. *"Not measured"* and *"nothing
+found"* are different sentences, and only one of them is honest when you have not looked.
+
+**What not to send.** Shapes and counts, never contents. No row data, no reader IPs or User-Agents —
+those are the columns half this contract exists to get rid of — no keys, tokens, connection strings,
+or private hostnames. *"A table of ~1600 rows returned 1000"* is the whole of what we needed to fix
+the ceiling defect; the rows themselves would have added nothing and created a problem.
+
+**What we do with it.** Every item above became code, a bench that dies if the fix is removed, and a
+dated entry naming the case. That last part is deliberate and a host asked for it: an abstract
+justification rots, a dated incident does not. In six months someone will read a field and ask why
+it exists, and the answer will name you.
+
 ## Versioning
 
 Semantic versioning on the package, independent of the `contract` number. Pin an **exact** version:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.151",
+  "version": "0.1.153",
   "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",

package/server/mesures.js

@@ -180,6 +180,22 @@ function relever() {
     // ⚠️ L'ÉCHELLE EST PUBLIÉE AVEC LES CHIFFRES. Sans elle, `p95sousMs: 250` ne dit pas si la
     // mesure suivante aurait pu être 251 ou 999 — un lecteur ne peut pas juger de sa précision.
     seauxMs: SEAUX_MS,
+    // ⚠️ LE DÉNOMINATEUR DE `routes`, ET IL MANQUAIT DEPUIS LE DÉBUT. Une famille sans échantillon
+    // est OMISE de `routes` — donc `routes: {}` ne distingue pas « aucun trafic sur la fenêtre »
+    // de « la mesure ne tourne pas ». Chez un hôte chargé la question ne se pose jamais : il y a
+    // toujours des entrées, et leur présence témoigne d'elle-même. Chez un hôte à 99 sessions,
+    // rien ne témoigne de rien.
+    //
+    // La règle vient d'un hôte, sur ses propres volumes : « les champs dont la valeur est son
+    // propre témoin à grande échelle ont besoin d'un témoin explicite à petite échelle ». Une
+    // petite installation n'est pas seulement privée d'occasions — elle perd du POUVOIR
+    // DISCRIMINANT, et un hôte plus chargé se trouve mieux instrumenté sans avoir rien instrumenté.
+    //
+    // ⚠️ ET LES DEUX CHAMPS VOISINS AVAIENT DÉJÀ RAISON, ce qui rend l'omission mesurable plutôt
+    // qu'opinable : `statuts` publie ses cinq clés à zéro, `boucleMs` publie `n: 0` avec des
+    // `null` explicites « plutôt que de publier un zéro qui se lirait la boucle est saine ». Trois
+    // champs frères du même objet, deux qui portent leur dénominateur et un qui l'oubliait.
+    familles: [...FAMILLES],
     routes,
     base: centiles(histoBase),
     statuts: { ...statuts },

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É.
@@ -577,23 +590,24 @@ async function compterBorne(chemin, cle) {
   // 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);
+  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
   }
 }
 
@@ -636,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