discovery-media-player 0.1.148 → 0.1.150

package/docs/HOST-CONTRACT.md

@@ -486,7 +486,8 @@ above: an unheard-of action answered *no* narrows this view rather than breaking
 `retentionSweep` says the instance *can* purge; it says nothing about what has piled up. The card
 gains a `purge` block counting the rows that still carry a reader IP or a raw User-Agent:
 
-    "purge": { "borne": 1000, "sessionsIp": 0, "sessionsUa": 0, "vuesUa": 0, "vide": true }
+    "purge": { "borne": 5000, "tronque": false, "lignes": { "sessions": 1908, "vues": 3200 },
+               "sessionsIp": 0, "sessionsUa": 0, "vuesUa": 0, "vide": true }
 
 `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 —
@@ -494,9 +495,70 @@ instance's live rows** — the condition under which those columns can eventuall
 `null` for the same reason: a failed probe must never read as a zero, because zero is the answer
 that authorises a deletion.
 
-The counts are **bounded** at `borne` rows and read one small column, so `1000` reads as *at least
-a thousand*, never as exactly. They run only under `&schema=1`, the mode where you have asked for
-the database.
+`lignes` is what the counter **looked at**, per table. A bare `0` cannot tell "purged" from "never
+written" from "the probe is aimed wrong"; the denominator separates them — *0 of 1908* means there
+was something to look at, *0 of 0* means the table is empty or out of reach and the zero proves
+nothing. It is `null` on the same terms as the counts.
+
+The counts are **bounded** at `borne` rows and read one small column. ⚠️ **`tronque` says whether
+anything was cut off**: when it is `true`, every number in the block is a *lower bound*, not a
+count. Without it a saturated `5000` would be indistinguishable from an exact five thousand — a
+wrong number that reads as right, which is worse than an absent one, because an absence makes you
+look and a number makes you conclude. `vide` stays correct either way: saturation can only make it
+`false`, never wrongly `true`.
+
+⚠️ **And `tronque` does not assume our bound is the only ceiling** — it did, for one release, and a
+host measured what that cost. PostgREST has a ceiling of its own, `db-max-rows`, set to **1000** by
+default on Supabase: the server returns 1000 rows however many you ask for. Comparing the received
+length against `borne` then compares against the wrong number, and a table of 1651 rows was
+published as `1000` **with `tronque: false`** — asserting an exactness it did not have.
+
+So the question asked is not *did I hit my bound* but **is there anything after what I received**:
+one row is requested past the last one received, by keyset cursor (`col=gt.<last>`, never by
+offset — a cursor is stable under concurrent writes, and it is this repository's pagination rule). A row returned proves more remain; none proves the lot was
+the whole — whichever ceiling produced it, without having to know it. **What this does not cover,
+stated rather than glossed:** a server ceiling of *zero* stays indistinguishable from an empty table
+by the response body alone. Reading the count from `Content-Range` under `Prefer: count=exact` has
+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.
+
+⚠️ **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
+that asks for more than that ceiling is not a large read, it is a **false belief**, and it stays
+invisible while your tables are small. So the question is worth asking of your own code as well as
+of ours: *does my client paginate, or do I believe that `limit=20000` returns 20 000 rows?*
+
+One host asked it of itself the day it found this in our counter, and the answer was not
+hypothetical: a statistics read ordered `created_at.asc` with no `limit` was seeing the **1000
+oldest** rows of 6424, so a "last opened" date read months stale for a link opened the day before,
+and every breakdown described the beginning of the history. They also count **32** reads asking for
+more than the ceiling — all latent on their volumes today, all live on an older installation.
+
+⚠️ **The sort direction decides how bad it gets.** A read that saturates while ordered `desc` loses
+the oldest rows; ordered `asc` it loses the newest — that is, the ones anyone is looking at. Same
+ceiling, same silence, opposite severity. Counting is indifferent to it, but anything that reads
+*content* under a ceiling should prefer `desc`.
+
+They run only under `&schema=1`, the mode where you have asked for the database.
+
+⚠️ **The purge attestation is a commitment, not a convenience.** Every column this player empties
+carries a `comment on column` whose text **begins with the exact marker**:
+
+    VIDE ET PLUS JAMAIS ECRITE depuis la <migration number>.
+
+Read it through `col_description()`. It is what *proves* a purge was applied — a count of zero does
+not, since it cannot tell "purged" from "never written". **We commit to two things**: to post it on
+every column a future migration empties, and not to reword that prefix. It is deliberately plain
+ASCII, without accent or apostrophe, so it survives encodings and needs no escaping.
+
+This used to be a convenience, designed for a person proving a purge. A host told us its inventory
+now reads it **mechanically**, crossing it with the residual counts to raise an alarm when values
+reappear beside an attestation. That is the moment an artefact becomes an interface — and the reason
+to commit is the failure mode: if we quietly stopped posting it, that alarm would go **silent
+without saying so**, a failure caused here and invisible there. A guard in this repository refuses
+any migration that empties a column without the marker, so undoing the commitment turns something
+red rather than turning something quiet.
 
 ⚠️ **Why this exists at all:** our tables live in *your* database, and your audit enumerates *your*
 tables — a dependency's schema occupies a zone nobody's inventory visits. Two integrating hosts

package/docs/RETENTION.md

@@ -242,23 +242,47 @@ is a number.
 **1. The rows.** Reading logs are deleted **13 months** after `at` / `last_at` by default. A host
 changes that through `config.retention` — whole months in `[1, 120]`.
 
-⚠️ **But the automatic sweep is strictly opt-in.** It runs only where a host has written
-`config.retention.balayage: true`; the `retention.run` action stays available without opt-in, because
-calling it *is* the decision. **On a host that has enabled neither, no row has ever been deleted, and
-the 13 months describe an intent rather than an event.** Anyone attesting a retention period should
-check which of the two is true of the installation in front of them, rather than quoting the default.
+⚠️ **But the automatic sweep is strictly opt-in**, and there are **three** states, not two — an
+integrating host measured the one we had left out:
+
+| state | how to tell | what you may claim |
+|---|---|---|
+| **off** | `retentionSweep` false, and no `retention.run` in your logs | nothing has ever been deleted; the window is a policy you have not applied |
+| **armed, never exercised** | armed, but no row has yet reached the window — check the age of your oldest row against it | nothing has ever been deleted **either**, and not for want of configuration |
+| **armed, and has deleted** | armed, and a run reported non-zero counts | the window is an *event*, and only here |
+
+⚠️ **The middle state is the misleading one**, because it has every appearance of the good one: armed,
+correct, and indistinguishable in its effects from being off — no deletion, no log, no evidence it
+works. A host reported exactly this: sweep armed, oldest row 63 days old, **zero rows past 13 months
+out of 1908**. Its first real execution will be roughly **eighteen months after it was armed**, on
+data nobody will have looked at, never having run in anger. Treat it as what it is — a guard that has
+never been exercised, with a deadline — and exercise it deliberately before then, on a copy or with
+`retention.run` and a short window, rather than discovering its behaviour the day it matters.
+
+Anyone attesting a retention period should establish which of the **three** is true of the
+installation in front of them, rather than quoting the default.
 
 **2. The values inside surviving rows.** Erased by 0026 and 0027 as soon as they are applied, and
 physically gone from the table once routine autovacuum has passed — no operator action, typically
 minutes to hours on an active table. This part does not wait for the 13 months.
 
 **3. Backups, write-ahead logs, exports and migration dumps.** **Outside this player's reach, and we
-neither set nor observe them.** They follow the hosting platform's own settings — on a managed
-provider, typically a point-in-time-recovery window plus a snapshot schedule, each with its own
-retention. A purge is complete end to end at *the later of*: the day 0026/0027 were applied plus the
-host's longest backup retention, and — for the rows themselves — whichever purge the host actually
-runs. **Ask the platform for two numbers: the PITR window and the oldest retained snapshot.** Until
-both have rolled past the migration date, earlier copies still hold the erased values.
+neither set nor observe them.** They follow the hosting platform's own settings — typically a
+point-in-time-recovery window plus a snapshot schedule, each with its own retention. Ask the platform
+for **the PITR window and the age of the oldest retained snapshot**; until they have rolled past the
+day 0026/0027 were applied, earlier copies still hold the erased values.
+
+⚠️ **Neither number is exposed by any API, and that matters more than it looks.** Two integrating
+hosts checked independently, on two different toolsets: the provider's API and its MCP tools return
+region, status and engine version — nothing about backups. **A human has to read them from the
+dashboard.** This is written here because the instruction above is *executable in appearance*: an
+agent following it will look for a tool, find none, and then either stop — or, the real risk, report
+the purge complete having skipped the one step it could not measure. If you cannot produce these two
+numbers, say so; do not round the sentence.
+
+⚠️ **And it is not always "the later of two".** An option that is not subscribed retains nothing, so
+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*.
 
 ## Limits stated rather than left unsaid
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.148",
+  "version": "0.1.150",
   "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/retention.js

@@ -410,9 +410,33 @@ function tick() {
  *
  * ⚠️ ON COMPTE DES LIGNES, PAS UN `count=exact`. La capacité `db` de l'hôte rend le corps de la
  * réponse, pas ses en-têtes : le compte de PostgREST voyage dans `Content-Range`, donc il serait
- * illisible sans élargir le contrat d'hôte — ce qu'un compteur de diagnostic ne justifie pas.
- * D'où un comptage BORNÉ : au plus `BORNE_RESTE` identifiants, une seule petite colonne. Atteindre
- * la borne se lit « au moins autant », jamais « exactement ».
+ * illisible sans élargir le contrat d'hôte — que des hôtes tiers implémentent eux-mêmes.
+ * D'où un comptage BORNÉ : au plus `BORNE_RESTE` identifiants, une seule petite colonne.
+ *
+ * ⚠️ CE CHOIX A UN COÛT, ET IL EST NOMMÉ ICI PLUTÔT QUE SUBI : lire des LIGNES, c'est dépendre des
+ * plafonds de qui les rend, et un hôte a mesuré que ce plafond peut être SOUS notre borne. Le
+ * compte d'en-tête n'a pas de plafond à deviner et ne transporte rien ; il est strictement
+ * supérieur, et le seul obstacle est le contrat. Tant que le contrat ne le rend pas, `resteApres`
+ * rattrape la seule chose qui rendait le nombre MENSONGER — l'affirmation d'exactitude.
+ *
+ * ⚠️ ET LA SATURATION SE DIT, ELLE NE SE DEVINE PAS — deux hôtes ont trouvé ce défaut dans la
+ * première version, le même jour, indépendamment. Elle demandait `limit=BORNE` et publiait
+ * `lignes.length` : sur une base portant cinq mille adresses, elle rendait `1000`, que rien ne
+ * distinguait d'un compte exact de mille. Un nombre faux qui se lit comme juste — pire qu'un
+ * nombre absent, parce que l'absence fait chercher et que le nombre fait conclure.
+ *
+ * Le remède vivait à trois cents lignes d'ici : `purgerRetention` rend `tronque` depuis toujours,
+ * pour exactement cette raison. On demande donc `BORNE + 1` : en recevoir autant prouve qu'il en
+ * reste, sans coûter une ligne de plus. `n` reste plafonné à la borne, et `tronque` dit qu'il faut
+ * le lire « au moins ».
+ *
+ * ⚠️ ET CE CORRECTIF ÉTAIT LUI-MÊME FAUX, D'UN CRAN PLUS LOIN — trouvé par un hôte réel QUATRE
+ * HEURES après sa publication. Il comparait le nombre de lignes reçues à NOTRE borne, donc il
+ * supposait que le seul plafond fût le nôtre. PostgREST en a un autre, `db-max-rows`, réglé à 1000
+ * par défaut chez Supabase : le serveur tronque EN AMONT, et la comparaison porte alors sur le
+ * mauvais nombre. Une table de 1651 lignes se lisait `1000` avec `tronque: false` — pire que la
+ * version d'avant, qui ne prétendait rien là où celle-ci AFFIRMAIT l'exactitude. `resteApres`
+ * ci-dessous pose désormais la seule question dont la réponse ne dépend d'aucun plafond.
  *
  * ⚠️ ET LE COÛT EST INVERSE DE L'INTUITION, donc il est dit plutôt que caché : quand il reste
  * beaucoup de lignes, la base s'arrête à la borne et c'est rapide ; quand il n'en reste AUCUNE,
@@ -423,7 +447,13 @@ function tick() {
  * ⚠️ UN ÉCHEC REND `null`, JAMAIS ZÉRO. Zéro est la réponse qui autorise à supprimer une colonne :
  * la fabriquer à partir d'une sonde en panne serait le pire mensonge que cette carte puisse faire.
  */
-const BORNE_RESTE = 1000;
+// ⚠️ CINQ MILLE, ET LE NOMBRE VIENT D'UNE MESURE. Il valait mille, et le banc écrit avec les
+// volumes RÉELS d'un hôte l'a fait rougir : sa table de vues en portait 1651. La borne saturait
+// donc dès le premier jour chez lui, et un compteur qui plafonne sous les volumes qu'il est censé
+// décrire ne décrit rien. Cinq mille couvre les deux hôtes connus avec de la marge, reste une
+// seule petite colonne à transférer, et `tronque` dit le reste. La borne est un plafond de COÛT,
+// pas une opinion sur ce qu'un hôte peut avoir.
+const BORNE_RESTE = 5000;
 
 const SONDES_RESTE = [
   ["sessionsIp", "commercial_doc_sessions", "session_id", "ip"],
@@ -431,6 +461,10 @@ const SONDES_RESTE = [
   ["vuesUa", "commercial_doc_views", "id", "ua"],
 ];
 
+/** Les tables regardées, pour le dénominateur — une par table, pas une par sonde. */
+const TABLES_RESTE = [["sessions", "commercial_doc_sessions", "session_id"],
+  ["vues", "commercial_doc_views", "id"]];
+
 /**
  * ⚠️ ET LA COLONNE DISPARUE EST UN ÉTAT CONNU, PAS UNE PANNE. Le jour où un exploitant supprime ces
  * colonnes — le geste que ce compteur sert à autoriser — la requête échoue avec le
@@ -443,27 +477,118 @@ const SONDES_RESTE = [
  */
 const COLONNE_ABSENTE = "42703";
 
-async function compterReste(table, cle, colonne) {
+/** `{ n, tronque }` — `n` nul veut dire indéterminé, jamais zéro. */
+const compte = (n, tronque) => ({ n, tronque });
+
+/**
+ * ⚠️ « MOINS QUE DEMANDÉ » NE PROUVE PAS LA FIN — ET C'EST UN HÔTE RÉEL QUI L'A MONTRÉ.
+ *
+ * La version précédente comparait le nombre de lignes reçues à NOTRE borne, et concluait « pas
+ * tronqué » dès qu'il était plus petit. Elle supposait que le seul plafond fût le nôtre. PostgREST
+ * en a un autre, `db-max-rows`, que Supabase règle à 1000 : le serveur rend 1000 lignes quoi qu'on
+ * demande. Sur une table de 1651 lignes, la carte a donc publié `1000` AVEC `tronque: false` —
+ * c'est-à-dire le défaut qu'on venait de corriger, déplacé d'un cran et AGGRAVÉ : la version d'avant
+ * ne prétendait rien, celle-là AFFIRMAIT que le nombre était exact.
+ *
+ * Le contrôle honnête ne porte donc pas sur une borne connue, mais sur la seule question dont la
+ * réponse ne dépend d'aucun plafond : « y a-t-il quelque chose APRÈS ce que j'ai reçu ? » On la
+ * pose en demandant UNE ligne au-delà de la dernière reçue. Une ligne rendue prouve qu'il en
+ * reste ; aucune prouve que le lot reçu était le tout — quel que soit le plafond qui l'a produit,
+ * et sans avoir à le connaître.
+ *
+ * ⚠️ PAR CURSEUR KEYSET (`cle=gt.<dernier>`), PAS PAR `offset` — et cette phrase est déjà écrite
+ * trois cent quatre-vingts lignes plus haut, au-dessus de `purgerParLots`, où elle dit la même
+ * chose depuis toujours : la garde de portabilité de la forge interdit `offset=`, et un curseur
+ * est de toute façon stable sous écriture concurrente. Première rédaction de cette sonde : par
+ * `offset`. La forge l'a refusée. C'est la SECONDE fois dans ce fichier qu'un remède déjà présent
+ * n'a pas été vu — après le drapeau `tronque` de `purgerParLots`. Un fichier dont on vient
+ * d'écrire la partie difficile se relit mal, et c'est un fait à traiter, pas une excuse.
+ *
+ * ⚠️ ET CE QU'ELLE NE COUVRE PAS EST DIT, PARCE QU'UNE GARDE MUETTE VAUT MOINS QUE PAS DE GARDE :
+ * un plafond serveur à ZÉRO reste indiscernable d'une table vide par le corps seul — les deux
+ * requêtes rendent zéro ligne. C'est la limite de la lecture par lignes, et la raison pour laquelle
+ * 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é.
+ */
+async function resteApres(chemin, cle, dernier) {
+  // Sans curseur lisible, la fin ne se prouve pas : « au moins » est le seul côté sûr.
+  if (dernier == null) return true;
+  try {
+    const suite = await PLAYER.db.request(
+      `${chemin}&${cle}=gt.${enc(String(dernier))}&order=${cle}.asc&limit=1`, { timeoutMs: 8000 });
+    // Pas de réponse analysable ⇒ on ne sait pas ⇒ « au moins ». Se tromper vers le minorant ne
+    // fait que sous-estimer ; se tromper vers l'exactitude fait conclure.
+    return !Array.isArray(suite) || suite.length > 0;
+  } catch { return true; }
+}
+
+async function compterBorne(chemin, cle) {
   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(
-      `${table}?select=${cle}&${colonne}=not.is.null&limit=${BORNE_RESTE}`,
-      { timeoutMs: 8000 },
-    );
-    return Array.isArray(lignes) ? lignes.length : null;
+      `${chemin}&order=${cle}.asc&limit=${BORNE_RESTE + 1}`, { timeoutMs: 8000 });
+    if (!Array.isArray(lignes)) return compte(null, false);
+    // Notre propre borne atteinte : la preuve est dans la ligne excédentaire, rien à demander.
+    if (lignes.length > BORNE_RESTE) return compte(BORNE_RESTE, true);
+    // 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]));
   } catch (e) {
-    if (e && e.details && e.details.code === COLONNE_ABSENTE) return 0;
-    return null;   // indéterminé — surtout pas zéro
+    if (e && e.details && e.details.code === COLONNE_ABSENTE) return compte(0, false);
+    return compte(null, false);   // indéterminé — surtout pas zéro
   }
 }
 
+const compterReste = (table, cle, colonne) =>
+  compterBorne(`${table}?select=${cle}&${colonne}=not.is.null`, cle);
+
+/**
+ * ⚠️ ET LE COMPTEUR PORTE CE QU'IL A REGARDÉ — un hôte nous l'a demandé, et il avait raison.
+ *
+ * `sessionsIp: 0` ne distingue pas trois choses : « purgé », « jamais écrit », et « la sonde vise à
+ * côté ». Les deux premières se valent pour qui veut supprimer une colonne ; la troisième est un
+ * mensonge. Le dénominateur les sépare : « 0 sur 1908 lignes examinées » dit qu'il y avait quelque
+ * chose à regarder, « 0 sur 0 » dit que la table est vide ou hors d'atteinte et que le zéro ne
+ * prouve rien.
+ *
+ * C'est notre propre règle anti-vacuité — un plancher compte la FORME RECONNUE, pas les choses
+ * comptées — appliquée partout dans `tools/` et absente d'ici jusqu'à ce qu'un lecteur la réclame.
+ *
+ * ⚠️ ET IL NE COÛTE PRESQUE RIEN, à l'inverse du compte filtré : sans filtre, la base s'arrête à la
+ * borne dès les premières lignes. Une par TABLE, pas une par sonde — deux des trois colonnes vivent
+ * dans la même.
+ */
+const compterLignes = (table, cle) => compterBorne(`${table}?select=${cle}`, cle);
+
 async function resteDeLaPurge() {
-  const comptes = await Promise.all(SONDES_RESTE.map(([, t, c, col]) => compterReste(t, c, col)));
-  const out = { borne: BORNE_RESTE };
-  SONDES_RESTE.forEach(([nom], i) => { out[nom] = comptes[i]; });
+  const [comptes, totaux] = await Promise.all([
+    Promise.all(SONDES_RESTE.map(([, t, c, col]) => compterReste(t, c, col))),
+    Promise.all(TABLES_RESTE.map(([, t, c]) => compterLignes(t, c))),
+  ]);
+  // ⚠️ ACCUMULATEURS NUS, comme celui de `fenetresValidees` plus haut et pour la même raison : la
+  // garde de forme reconnaît `Object.create(null)`, et une écriture indexée par autre chose qu'un
+  // littéral n'a alors aucun prototype à polluer. Les clés viennent ici de constantes du fichier,
+  // mais un objet nu ne coûte rien et la propriété se lit sans avoir à remonter leur provenance.
+  const parTable = Object.create(null);
+  TABLES_RESTE.forEach(([nom], i) => { parTable[nom] = totaux[i].n; });
+  const out = Object.create(null);
+  out.borne = BORNE_RESTE;
+  // ⚠️ UN SEUL DRAPEAU POUR TOUT LE BLOC, parce qu'il ne sert qu'à une chose : dire au lecteur que
+  // les nombres qu'il voit sont des minorants. Un drapeau par compte suggérerait qu'on peut faire
+  // 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;
+  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
   // sait pas » ne doit jamais se lire comme « c'est bon ».
-  out.vide = comptes.some((n) => n === null) ? null : comptes.every((n) => n === 0);
+  // ⚠️ `vide` RESTE JUSTE MÊME SATURÉ, et c'est ce qui compte : c'est le champ qui autorise le
+  // retrait d'une colonne, et la saturation ne peut le rendre que FAUX — jamais vrai à tort.
+  out.vide = comptes.some((c) => c.n === null) ? null : comptes.every((c) => c.n === 0);
   return out;
 }