discovery-media-player 0.1.147 → 0.1.148

package/docs/HOST-CONTRACT.md

@@ -482,6 +482,27 @@ forwarded re-shares of their own links included, because they caused those readi
 changes for a role you already answer *yes* to. If your table predates `list.all`, see the warning
 above: an unheard-of action answered *no* narrows this view rather than breaking it.
 
+⚠️ **`?contract=1&schema=1` now tells you what is still stored, not only what you may purge.**
+`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 }
+
+`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 —
+`false` means rows remain, and **`null` means at least one probe did not answer**. A count is
+`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.
+
+⚠️ **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
+found 2361 rows still carrying these columns, and they found them because a third party asked a
+question about its own database, not because anything told them.
+
 ⚠️ **The reader IP is erased, and a direct query of your own will start seeing nothing.** The
 sessions table carried `ip` in the clear. `0.1.147` stops serving it — no player path reads it back,
 so nothing in this contract changes — stops writing it, and ships migration **0026**, which erases

package/docs/RETENTION.md

@@ -177,11 +177,35 @@ end on a populated database: 200 rows kept, 200 addresses gone after a routine v
 replayable with no further effect. **The erasure is therefore complete today.** What is deferred is
 the shape of the schema, not the data.
 
-**When the columns are removed, and how to know the moment has come.** Not until **every deployed
-host runs a version that no longer writes them** — the release carrying 0026 and 0027, or later.
-Until then a `DROP` of any of the three would fail every session and view write of a host that
-applies migrations before deploying. The check is not a date: it is whether the oldest player version
-still in service is at or past that release.
+**Dropping the three columns is YOUR decision, not a migration we will ship.** This section used to
+say the removal would come "in a later release", which was misleading: **we cannot know which player
+version runs against your database, and you can.** A `DROP` is only safe once every instance writing
+to that database is on `0.1.147` or later; on `0.1.145` and earlier PostgREST would reject every
+session and view write, with an error naming a column rather than a version. Shipping that `DROP` in
+`supabase/migrations/`, which every host replays, would hand the same irreversible gesture to hosts
+whose deployment we have never seen. So it stays where the answer is known — with you.
+
+**How to know the moment has come.** `?contract=1&schema=1` reports `purge.vide`. When it is `true`
+on every instance pointing at that database, and every one of them is on `0.1.147` or later, nothing
+writes those columns any more. Then, if you want the schema tidied:
+
+```sql
+alter table public.commercial_doc_sessions drop column if exists ip;
+alter table public.commercial_doc_sessions drop column if exists ua;
+alter table public.commercial_doc_views    drop column if exists ua;
+```
+
+⚠️ **This buys tidiness, not erasure — the erasure already happened.** `0026` and `0027` are what
+removed the values, and routine autovacuum is what removed them from the pages (measured on a real
+host: four seconds after the second migration, no lock, nothing triggered by hand). A `DROP` on
+already-empty columns rewrites nothing and frees nothing. Run it because a schema should say what it
+holds, not because anything is still there.
+
+⚠️ **And you lose the attestation with the column.** The comment carried by each column — readable
+through `col_description()` — is what proves the purge was applied; a count of zero does not, since
+it cannot tell "purged" from "never written". Capture that proof before dropping if you may need to
+show it. After the drop, `purge.vide` still reads `true`: an absent column is a known state, not an
+unknown one.
 
 **Why the column itself survives, for now.** A migration here must be safe to apply *while the
 previous version of the player is running* — that rule is what makes the deployment order harmless,

package/package.json

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

@@ -801,6 +801,18 @@ async function handlerMesure(req, res) {
           ...(String(q.schema || "") === "1"
             ? await require("./schema").sonderTout()
             : require("./schema").etatDuSchema()) },
+        // ⚠️ CE QUI S'ACCUMULE, PAS SEULEMENT CE QU'ON PEUT PURGER. `retentionSweep` ci-dessus dit
+        // « je PEUX purger » ; il ne dit rien de ce qui est là. Nos tables vivent dans la base de
+        // l'hôte, et l'audit d'un hôte énumère SES tables : le schéma d'une dépendance occupe une
+        // zone que les inventaires de personne ne visitent. Deux hôtes ont trouvé 2361 lignes
+        // portant encore une adresse ou un agent brut — parce qu'un TIERS avait posé une question
+        // sur SA base, pas parce que quoi que ce soit le leur avait dit.
+        //
+        // Sous `&schema=1` seulement : c'est une lecture de la base, et sans le paramètre cette
+        // carte garde sa propriété de répondre quand plus rien ne répond.
+        ...(String(q.schema || "") === "1"
+          ? { purge: await require("./retention").resteDeLaPurge() }
+          : {}),
         // « L'hôte peut-il créer un lien en son nom propre ? » — configuré, pas seulement
         // possible. Un hôte qui oublie le secret reçoit un 401 qui ressemble à un droit
         // manquant ; ce booléen le lui dit sans qu'il ait à essayer.

package/server/retention.js

@@ -391,4 +391,80 @@ function tick() {
     .catch((e) => { try { PLAYER.errors.capture(e, { route: "retention", benin: true }); } catch { /* jamais bloquant */ } });
 }
 
-module.exports = { init, purgerRetention, tick, borne };
+/**
+ * CE QUI RESTE DE L'HÉRITAGE, CHEZ CET HÔTE — les lignes qui portent encore une adresse IP ou un
+ * User-Agent brut.
+ *
+ * ⚠️ POURQUOI CE COMPTEUR EXISTE, ET C'EST UN HÔTE QUI L'A DIT. Nos tables vivent dans la base de
+ * nos hôtes, et l'audit d'un hôte énumère SES tables : le schéma d'une dépendance occupe une zone
+ * que les inventaires de personne ne visitent. Deux hôtes ont découvert 2361 lignes portant ces
+ * colonnes — non pas en surveillant, mais parce qu'un TIERS avait posé une question sur SA base.
+ * `retentionSweep` dit « je PEUX purger » ; il ne dit pas CE QUI S'ACCUMULE. Ce compteur le dit,
+ * chez chacun, sans que personne ait à y penser.
+ *
+ * ⚠️ ET IL RÉPOND À LA QUESTION QUI DÉCIDE DU RETRAIT DES COLONNES. `0026` et `0027` VIDENT sans
+ * supprimer, parce qu'une migration doit rester sûre pendant que la version précédente du code
+ * tourne. Le retrait attend que plus aucune version supportée ne les écrive — une condition qu'on
+ * ne peut aujourd'hui que SUPPOSER, en croyant savoir quelle version tourne chez qui. `vide` la
+ * rend LISIBLE.
+ *
+ * ⚠️ 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 ».
+ *
+ * ⚠️ 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,
+ * elle parcourt la table pour ne rien trouver. Le cas cher est le cas terminal — celui où ce
+ * compteur a fini son office et disparaîtra avec les colonnes qu'il surveille. Il ne s'exécute
+ * d'ailleurs que sur `?contract=1&schema=1`, le seul mode où l'appelant demande la base.
+ *
+ * ⚠️ 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;
+
+const SONDES_RESTE = [
+  ["sessionsIp", "commercial_doc_sessions", "session_id", "ip"],
+  ["sessionsUa", "commercial_doc_sessions", "session_id", "ua"],
+  ["vuesUa", "commercial_doc_views", "id", "ua"],
+];
+
+/**
+ * ⚠️ 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
+ * `42703` de PostgreSQL, « colonne inexistante ». Rendre `null` ferait alors lire « on ne sait
+ * pas » au moment EXACT où l'on sait le mieux : plus rien ne peut porter une colonne qui n'existe
+ * plus. Le compteur deviendrait aveugle précisément quand son sujet est réglé.
+ *
+ * Toute autre erreur reste `null`. Et un hôte dont la capacité `db` ne rend pas le corps analysé
+ * retombe sur `null` : ne pas savoir est le côté sûr, puisque zéro est ce qui autorise à supprimer.
+ */
+const COLONNE_ABSENTE = "42703";
+
+async function compterReste(table, cle, colonne) {
+  try {
+    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;
+  } catch (e) {
+    if (e && e.details && e.details.code === COLONNE_ABSENTE) return 0;
+    return null;   // indéterminé — surtout pas zéro
+  }
+}
+
+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]; });
+  // ⚠️ 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);
+  return out;
+}
+
+module.exports = { init, purgerRetention, tick, borne, resteDeLaPurge, BORNE_RESTE };