discovery-media-player 0.1.127 → 0.1.129

package/docs/HOST-CONTRACT.md

@@ -38,6 +38,7 @@ need.
   "presenceStrict": true,
   "presenceJetons": true,
   "presenceDurcissement": "inconnu",
+  "presenceFusion": "inconnu",
   "retentionSweep": false,
   "hostShare": true,
   "hostMail": true,
@@ -73,13 +74,33 @@ The three `presence*` fields report what the host has **observed**, not what it
 | `presenceJetons` | measured — the host actually signed a throwaway token, so `PLAYER_PRESENCE_SECRET` works |
 | `presenceStrict` | **effective** — `PLAYER_PRESENCE_STRICT` is set *and* tokens can be issued. A closed door announced over an open one would be the worse failure |
 | `presenceDurcissement` | `actif` (a hardened call came back), `degrade` (migration 0018 is missing), `inconnu` (nothing attempted in this process — **not** a green light, and process-local: another instance may have seen otherwise) |
-
-⚠️ **Before you upgrade, do not read `presenceDurcissement`.** It is a *report of execution*: on an
-instance where nothing is running it says `inconnu`, which means *nobody looked* — not *the migration
-is there*. A pre-flight check built on it silently passes on every idle host, and the missing
-migration is then discovered at the first presentation, i.e. at the worst moment. Ask
-`GET /api/doc?contract=1&schema=1` and read **`schema.durcissementBase`** instead: it asks the
-database, so it answers a global fact.
+| `presenceFusion` | `actif` (a heartbeat used the fused contract — one round trip instead of two), `degrade` (migration 0019 is missing: heartbeats cost 3 round trips instead of 2, nothing breaks), `inconnu` (no heartbeat served in this process). Same three states, same trap, same reading rule as the row above |
+
+⚠️ **Before you upgrade, do not read `presenceDurcissement` or `presenceFusion`.** They are *reports
+of execution*: on an instance where nothing is running they say `inconnu`, which means *nobody
+looked* — not *the migration is there*. A pre-flight check built on one of them silently passes on
+every idle host, and the missing migration is then discovered at the first presentation, i.e. at the
+worst moment. Ask `GET /api/doc?contract=1&schema=1` and read **`schema.durcissementBase`** and
+**`schema.fusionBase`** instead: they ask the database, so they answer a global fact.
+
+⚠️ **And on a serverless host, `inconnu` is not the exception — it is the normal answer, forever.**
+This paragraph used to say *"on an instance where nothing is running"*, which reads as a description
+of an **idle** deployment. Field data from the second host corrected it: a real presentation ran on
+their instance, with a participant, on the very day both fields read `inconnu`. Nothing was idle —
+the presentation had simply ended, and the short-lived process answering `/api/doc` was never the one
+that served a heartbeat. On a platform where each request may be a fresh process, that is the
+**structural** case, not an edge case: a host serving presentations daily can read `inconnu` every
+single time you ask.
+
+So the two fields answer *"did this process, right now, see it work?"* — useful to confirm a fix on a
+long-lived process, worthless as an inventory anywhere else. The durable signals live in `schema`:
+`fusionBase` and `durcissementBase` for the migrations, and `schema.presence.avecJeton` crossed with
+`presentationsActives` for actual traffic — those are read from the database and survive the process
+that answers.
+
+⚠️ **A corollary worth keeping:** *"our instances are idle"* and *"our instances are lightly used"*
+are different claims, and only the second was true here. The distinction matters because a defect
+that needs traffic to appear had real opportunities the whole time it was assumed to have none.
 
 | `durcissementBase` | meaning |
 |---|---|
@@ -87,9 +108,32 @@ database, so it answers a global fact.
 | `absente` | 0018 is missing: apply it **before** setting `PLAYER_PRESENCE_STRICT`, or bootstraps will be refused with `503` |
 | `indetermine` | the question could not be asked — neither a yes nor a no |
 
-The probe writes nothing: it calls the function with `p_anon_cap = 0`, so a non-existent row exits
-through the *capped* branch and returns before the insert. A real-Postgres test asserts that no row
-appears. A host missing 0018 is also logged once an hour, so an idle instance still finds out.
+The same answer carries **`schema.fusionBase`**, for migration `0019`, with the same three values.
+Both come from **one** call in the normal case: `0019` succeeds `0018` and its argument set *contains*
+it, so a call the long contract accepts proves both at once. The short contract is only asked again
+when the long one is missing — i.e. exactly on the host that is behind and owes a precise answer.
+
+| `fusionBase` | meaning |
+|---|---|
+| `applique` | `0019` is in the database — a presence heartbeat costs **2**† database round trips (**20**† ops/s for 250 attendees) |
+| `absente` | `0019` is missing: **nothing breaks**, a heartbeat costs **3**† round trips (**30**† ops/s for 250 attendees). Applying it needs no redeploy — the player picks it up within a minute |
+| `indetermine` | the question could not be asked — neither a yes nor a no |
+
+⚠️ Unlike `0018`, a missing `0019` is a **cost**, not a risk: read it when you are sizing an
+instance, not when you are deciding whether it is safe to run. A host missing it is also logged once
+an hour, with the exact figures, so an idle instance still finds out.
+
+† **Recomputed from the code on every CI run** by `charge/coutParGeste.test.js`, which measures both
+regimes — the fallback still lives in the code, so the *without-`0019`* figure is a measurement, not
+a number remembered from an older release. The build fails when this document and the bench disagree.
+⚠️ **A number without † in this repository's documentation is hand-written: it was true once, and
+nothing has checked it since.**
+
+The probe writes nothing, for **two independent reasons**: `p_page = null` on a slug that does not
+exist leaves through `0019`'s *introuvable* branch before the insert, and `p_anon_cap = 0` already
+left through the previous contract's *capped* branch. Two reasons rather than one, because a
+diagnostic probe is the worst place to discover a regression. A real-Postgres test asserts that no
+row appears. A host missing 0018 is also logged once an hour, so an idle instance still finds out.
 
 That parameter **is** the one part of this card that needs the database, and only when you ask for
 it. `verdict` is then one of:

package/docs/README.md

@@ -17,7 +17,7 @@ no document assumes you have read the others.
 |---|---|
 | [`CONFIGURATION.md`](CONFIGURATION.md) | Every environment variable. An instance is described entirely by its environment — there is no configuration file, on purpose. |
 | [`MIGRATIONS.md`](MIGRATIONS.md) | What happens to a database **already in service** when the player expects a newer schema. (French.) |
-| [`RETENTION.md`](RETENTION.md) | The declared perimeter of data retention: every personal-data column has a written policy, and CI enforces that the list is complete. Also an export of the package: `require.resolve("discovery-media-player/retention")`. (French.) |
+| [`RETENTION.md`](RETENTION.md) | The declared perimeter of data retention: every personal-data column has a written policy, and CI enforces that the list is complete. Also an export of the package: `require.resolve("discovery-media-player/retention")`. |
 
 ## You are contributing, or publishing a version
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.127",
+  "version": "0.1.129",
   "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",
@@ -68,8 +68,8 @@
     "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",
-    "lint:fix": "eslint bin context server src build --fix",
+    "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: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",
     "test:e2e": "node -e \"require('fs').existsSync('vitest.e2e.config.mjs')||(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 --config vitest.e2e.config.mjs",
@@ -83,13 +83,16 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "axe-core": "^4.13.0",
+    "dockerfile-ast": "0.7.1",
     "esbuild": "^0.28.2",
     "eslint": "^10.8.1",
+    "fast-check": "4.9.0",
     "jsdom": "^30.0.1",
     "playwright-core": "^1.62.1",
     "typescript": "^5.5.4",
     "typescript-eslint": "^8.46.4",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "2.9.0"
   },
   "dependencies": {
     "pdfjs-dist": "6.2.108"

package/server/handler.js

@@ -624,6 +624,17 @@ async function handler(req, res) {
         presenceDurcissement: (() => {
           try { return require("./presentations").etatDurcissementBootstrap(); } catch { return "inconnu"; }
         })(),
+        // ⚠️ LE CHEMIN FUSIONNÉ EST-IL EMPRUNTÉ ? Sans ce champ, un hôte à qui 0019 manque retombe en
+        // silence à trois allers-retours par battement : correct, mais deux fois plus cher sur le
+        // chemin le plus chaud du produit, et RIEN ne le dirait. Une dégradation qu'on ne peut pas
+        // observer est une dégradation qu'on découvre à la facture — ou jamais.
+        //
+        // ⚠️ Mêmes trois états, même piège : « inconnu » veut dire « personne n'a battu dans ce
+        // processus », pas « la migration manque ». Pour la question d'avant-déploiement, c'est
+        // `schema.fusionBase` qu'il faut lire — elle, elle interroge la base.
+        presenceFusion: (() => {
+          try { return require("./presentations").etatFusionBattement(); } catch { return "inconnu"; }
+        })(),
         // ⚠️ LES JETONS DE PRÉSENCE SONT-ILS RÉELLEMENT ÉMIS ? Sans ce booléen, un exploitant qui vient
         // de poser `PLAYER_PRESENCE_SECRET` n'a AUCUN moyen de vérifier que son réglage a pris : la
         // carte affiche `presence: {0,0}` aussi bien quand le secret est actif que quand la variable est

package/server/presentations.js

@@ -839,6 +839,25 @@ function signatureAbsente(erreur) {
 // silence. Un « oui » (la signature existe) n'a pas besoin d'expirer : une fonction ne disparaît pas.
 let _bumpSansDurcissementJusqua = 0;
 const MEMO_SANS_DURCISSEMENT_MS = 60 * 1000;
+// ⚠️ CE QUE CE PROCESSUS A CONSTATÉ DU CHEMIN FUSIONNÉ — pas ce qu'il espère. Trois états, comme
+// pour le durcissement, et pour la même raison : « pas dégradé » n'est pas « vérifié ». Un
+// processus qui vient de démarrer n'a rien tenté ; rendre « actif » annoncerait une propriété sur
+// la foi d'une absence d'observation.
+//
+// ⚠️ ET C'EST UN RAPPORT D'EXÉCUTION, PAS UN INVENTAIRE. Il ne se lit pas avant un déploiement : au
+// repos il vaut « inconnu », ce qui veut dire « personne n'a regardé ». La question « la migration
+// est-elle là ? » se pose à la BASE — c'est `schema.fusionBase`, qui la lui pose vraiment.
+let _etatFusion = "inconnu";
+function etatFusionBattement() {
+  // ⚠️ MÊME LECTURE QUE `etatDurcissementBootstrap`, DÉLIBÉRÉMENT. Les deux champs partagent leur
+  // vocabulaire et se lisent côte à côte dans la carte : leur donner des règles d'expiration
+  // différentes serait un piège pour qui les compare. Tant que le mémo court, la dernière
+  // observation vaut ; passé lui, une preuve NÉGATIVE périmée retombe sur l'ignorance et jamais sur
+  // la confiance. Un « oui » n'expire pas — une fonction ne disparaît pas toute seule.
+  if (Date.now() < _bumpSansFusionJusqua) return "degrade";
+  return _etatFusion === "degrade" ? "inconnu" : _etatFusion;
+}
+
 // ⚠️ MÉMO DU CONTRAT FUSIONNÉ (0019), MÊME PATRON QUE 0018. La fusion est FONCTION-SEULE : aucune
 // colonne à sonder, donc on la DEMANDE et on retient l'échec, sinon un hôte non migré paierait un
 // aller-retour perdu à chaque battement. Soixante secondes : assez pour ne pas insister, assez court
@@ -879,6 +898,10 @@ function erreurDurcissementAbsent() {
 // est là — donc 0018 aussi, elle la précède — et le durcissement est bien celui qu'on a demandé.
 async function appelerBumpFusionne(corps, durcissementVoulu) {
   const reponse = await PLAYER.db.request("rpc/player_attendance_bump", { method: "POST", body: corps });
+  // L'appel est REVENU : le contrat à 13 arguments existe. Ce qui se mesure est le RETOUR, jamais
+  // l'intention de partir — et un durcissement demandé qui revient par ici est bien appliqué, 0019
+  // succédant à 0018 elle ne peut pas être là sans elle.
+  _etatFusion = "actif";
   if (durcissementVoulu) _etatDurcissement = "actif";
   // ⚠️ ON PROJETTE PLUTÔT QUE DE RENDRE LA LIGNE TELLE QUELLE — une garde de ce dépôt l'exige, et
   // elle a raison ici : le jour où la RPC rendra une colonne de plus, elle ne traversera pas cette
@@ -1033,6 +1056,7 @@ async function recordAttendance(slug, participant, { presentation = null, ipHash
         // 0019 n'est pas appliquée. On arme le mémo et on recommence par le chemin classique, qui
         // lira la présentation et décidera du présentateur ici — SANS rien perdre. Rien à signaler à
         // l'exploitant : le battement reste exact, il coûte simplement l'aller-retour d'avant.
+        _etatFusion = "degrade";
         _bumpSansFusionJusqua = Date.now() + MEMO_SANS_FUSION_MS;
         return recordAttendance(slug, participant,
           { presentation, ipHash, anonCap, hasToken, onlyIfUnclaimed, controlHash, sansFusion: true });
@@ -1350,4 +1374,4 @@ async function listPresentationsForDoc(docId, email, isAdmin, autoriseLarge) {
 module.exports = {
   reacteurDepuisJeton,
   purgerPerimees,
-  messagePublic, CHAMPS_PUBLICS, etatDurcissementBootstrap, signatureAbsente, cheminPieceJointe, init, createPresentation, getPresentation, setPage, endPresentation, addMessage, listMessages, toggleReaction, editMessage, deleteMessage, setChatLock, createUploadUrl, reclaimPresentation, touchPresentation, listActivePresentations, handoverPresentation, endPresentationByOwner, recordAttendance, presentationStats, listPresentationsForDoc, switchPresentationDoc, setPresentationContent , STALE_MS};
+  messagePublic, CHAMPS_PUBLICS, etatDurcissementBootstrap, etatFusionBattement, signatureAbsente, cheminPieceJointe, init, createPresentation, getPresentation, setPage, endPresentation, addMessage, listMessages, toggleReaction, editMessage, deleteMessage, setChatLock, createUploadUrl, reclaimPresentation, touchPresentation, listActivePresentations, handoverPresentation, endPresentationByOwner, recordAttendance, presentationStats, listPresentationsForDoc, switchPresentationDoc, setPresentationContent , STALE_MS};

package/server/schema.js

@@ -313,6 +313,11 @@ async function vraimentSonderTout() {
     return {
       ...etatDuSchema(), verdict: "indetermine",
       durcissementBase: "indetermine", durcissementBaseCouvre: PORTEE_DURCISSEMENT,
+      // ⚠️ LE CHAMP DOIT ÊTRE LÀ ICI AUSSI, pour la raison qui a valu son correctif au voisin : un
+      // champ ABSENT ne se distingue pas d'un contrat plus ancien, et `undefined !== "applique"`
+      // est vrai par accident. Un hôte qui teste avant de déployer mérite un « je ne sais pas »
+      // explicite plutôt qu'un silence qui ressemble à un non.
+      fusionBase: "indetermine", fusionBaseCouvre: PORTEE_FUSION,
     };
   }
   // ⚠️ LE TÉMOIN VIENT DE RÉPONDRE : tout « non » encore en cache est SUSPECT — il peut dater
@@ -324,7 +329,7 @@ async function vraimentSonderTout() {
   const etat = etatDuSchema();
   await ajouterSansRang(etat);
   await ajouterPresence(etat);
-  await ajouterDurcissement(etat);
+  await ajouterMigrationsDePresence(etat);
   return etat;
 }
 
@@ -378,12 +383,81 @@ const PORTEE_DURCISSEMENT =
   + "C'est ce champ-ci qu'on lit AVANT un déploiement ; « indetermine » = la question n'a pas pu "
   + "être posée, ce n'est ni un oui ni un non.";
 
-async function ajouterDurcissement(etat) {
-  const corps = {
-    p_slug: SLUG_SONDE_DURCISSEMENT, p_key: "sonde", p_ip_hash: null, p_page: 1,
+// ⚠️ MÊME DISTINCTION, POUR 0019 : `fusionBase` est une propriété de la BASE, `presenceFusion` (la
+// carte) est ce que CE processus a constaté en servant des battements. Le second vaut « inconnu » au
+// repos — c'est-à-dire « personne n'a regardé » — et ne peut donc pas servir de contrôle avant
+// déploiement. On a déjà écrit une consigne de pré-vol sur un champ qui refuse de se prononcer sans
+// observation ; celui-ci existe pour qu'on n'ait pas à recommencer.
+const PORTEE_FUSION =
+  "propriété de la BASE (migration 0019), globale à toutes les instances — à ne pas confondre avec "
+  + "presenceFusion, qui est ce que CE processus a constaté en servant des battements. Sans 0019, "
+  + "rien ne casse : un battement coûte 3 allers-retours au lieu de 2. « indetermine » = la question "
+  + "n'a pas pu être posée, ce n'est ni un oui ni un non.";
+
+// ⚠️ DEUX MIGRATIONS, UNE SEULE SONDE DANS LE CAS NORMAL. 0019 succède à 0018 et son jeu
+// d'arguments CONTIENT le sien : un appel qui passe le contrat à 13 arguments prouve donc les deux
+// d'un coup. On ne repose la question du durcissement que si le contrat long n'existe pas — c'est-
+// à-dire sur un hôte en retard, qui est exactement celui à qui l'on doit une réponse précise.
+//
+// ⚠️ ET LA SONDE N'ÉCRIT TOUJOURS RIEN, POUR DEUX RAISONS INDÉPENDANTES. `p_page: null` sur un slug
+// qui n'existe pas sort par la branche « introuvable » de 0019, avant l'insert ; et `p_anon_cap: 0`
+// sortait déjà par la branche « capped » du contrat précédent. Deux raisons plutôt qu'une, parce
+// qu'une sonde de diagnostic qui écrirait serait le pire endroit où découvrir une régression.
+// ⚠️ UN SEUL ENDROIT QUI PARLE, PARCE QU'IL Y A PLUSIEURS RAISONS DE PARLER. La carte est publique
+// donc appelable en boucle : un journal sans frein deviendrait une arme. Une fois par heure et par
+// motif — et jamais bloquant, un diagnostic qui tombe en panne en diagnostiquant ne diagnostique
+// plus rien.
+async function journaliser(cle, message) {
+  try {
+    if (await PLAYER.limits.allow(cle, 1, 3600)) PLAYER.errors.capture(new Error(message), { route: "schema" });
+  } catch { /* jamais bloquant */ }
+}
+
+async function ajouterMigrationsDePresence(etat) {
+  const commun = {
+    p_slug: SLUG_SONDE_DURCISSEMENT, p_key: "sonde", p_ip_hash: null,
     p_name: "", p_avatar: "", p_is_member: false, p_is_presenter: false,
     p_max_gap_ms: 0, p_anon_cap: 0, p_has_token: null, p_only_if_unclaimed: true,
   };
+  const estSignatureAbsente = (erreur) => {
+    try { return require("./presentations.js").signatureAbsente(erreur); } catch { return false; }
+  };
+
+  etat.fusionBaseCouvre = PORTEE_FUSION;
+  try {
+    await PLAYER.db.request("rpc/player_attendance_bump",
+      { method: "POST", body: { ...commun, p_page: null, p_control_hash: null } });
+    // Le contrat long a répondu : 0019 est là, donc 0018 aussi — elle la précède et 0019 reprend
+    // ses arguments. On ne repose pas une question dont la réponse vient d'être prouvée.
+    etat.fusionBase = "applique";
+    etat.durcissementBase = "applique";
+    etat.durcissementBaseCouvre = PORTEE_DURCISSEMENT;
+    return;
+  } catch (erreur) {
+    if (!estSignatureAbsente(erreur)) {
+      // ⚠️ UNE PANNE NE PROUVE RIEN — NI POUR L'UNE NI POUR L'AUTRE. Insister avec un second appel
+      // ne ferait que frapper une base déjà en difficulté pour en tirer la même absence de réponse.
+      etat.fusionBase = "indetermine";
+      etat.durcissementBase = "indetermine";
+      etat.durcissementBaseCouvre = PORTEE_DURCISSEMENT;
+      await journaliser("schema:sonde-presence-muette",
+        "sonde des migrations de présence (0018/0019) sans réponse exploitable : ni confirmées, ni "
+        + "infirmées — " + ((erreur && erreur.message) || erreur));
+      return;
+    }
+    etat.fusionBase = "absente";
+    // ⚠️ ET ON LE DIT. C'est même toute la raison d'être de cette sonde : sans elle, un hôte à qui
+    // 0019 manque paie deux fois le chemin le plus chaud du produit sans que rien ne le signale.
+    // Le message dit la dégradation EXACTE — pas « ça ne marche pas », qui n'aide personne à
+    // décider si ça vaut une migration.
+    await journaliser("schema:fusion-absente",
+      "migration 0019-presence-lit-la-presentation.sql ABSENTE : rien ne casse, mais chaque "
+      + "battement de présence coûte 3 allers-retours base au lieu de 2 — soit environ 30 op/s au "
+      + "lieu de 20 pour 250 participants. L'appliquer ne demande aucun redéploiement.");
+    // On ne sait toujours rien de 0018 : le contrat court se demande à part, ci-dessous.
+  }
+
+  const corps = { ...commun, p_page: 1 };
   try {
     await PLAYER.db.request("rpc/player_attendance_bump", { method: "POST", body: corps });
     etat.durcissementBase = "applique";
@@ -391,8 +465,7 @@ async function ajouterDurcissement(etat) {
     // ⚠️ TROIS ISSUES, ET LA TROISIÈME N'EST PAS UNE DES DEUX AUTRES. Seule la signature absente
     // prouve que 0018 manque ; une panne réseau ou un 500 ne prouvent RIEN, et les compter comme
     // « absente » serait le défaut qu'on a mis trois versions à retirer d'ailleurs.
-    let absente = false;
-    try { absente = require("./presentations.js").signatureAbsente(erreur); } catch { /* module absent */ }
+    const absente = estSignatureAbsente(erreur);
     etat.durcissementBase = absente ? "absente" : "indetermine";
     // ⚠️ ET ON LE DIT, PAS SEULEMENT DANS LA CARTE. Une garde de ce dépôt refuse qu'une écriture soit
     // rattrapée en silence, et elle a raison ici pour une raison qu'elle ne pouvait pas connaître :

package/server/shares.js

@@ -139,12 +139,27 @@ async function logView(share, { event, page, maxPage, seconds, sessionId, ua })
  * d'administration) : sans restriction, un commercial verrait à qui d'autre le document a été
  * envoyé — donc les prospects de ses collègues.
  */
+// ⚠️ UNE SEULE DÉFINITION DE LA FENÊTRE D'ANALYTIQUE, PARCE QU'ELLE ÉTAIT DANS UNE FONCTION SUR DEUX.
+// `overview()` bornait sa lecture à 24 mois glissants ; `listSharesForDoc`, quarante lignes plus haut,
+// lisait TOUT l'historique d'un document. Deux lectures des mêmes tables d'événements, deux règles —
+// et la seconde n'était écrite nulle part : elle se déduisait d'une absence.
+//
+// ⚠️ ET LE BORNAGE EST TEMPOREL, PAS EN NOMBRE DE LIGNES — la mesure l'impose. PostgREST plafonne à
+// 1 000 lignes ici (constaté par un incident, cf. le commentaire d'`overview()` plus bas) : un
+// `limit` inférieur mordrait DÉJÀ sur notre pire document (662 lignes), et un `limit` supérieur
+// serait silencieusement ramené à 1 000 — donc un drapeau « tronqué » calculé sur la longueur
+// MENTIRAIT. C'est `selectAll`, qui pagine par `Range`, qui met à l'abri du plafond ; la fenêtre,
+// elle, borne le volume. Le patron « borné-ordonné-parlant » s'applique donc par sa borne TEMPORELLE.
+const FENETRE_ANALYTIQUE_MOIS = 24;
+const depuisFenetre = () =>
+  new Date(Date.now() - FENETRE_ANALYTIQUE_MOIS * 30 * 24 * 60 * 60 * 1000).toISOString();
+
 async function listSharesForDoc(docId, owner) {
   const id = enc(String(docId || ""));
   const filtreOwner = owner ? `&created_by=eq.${enc(low(owner))}` : "";
   const [shares, views] = await Promise.all([
     PLAYER.db.request(`commercial_doc_shares?doc_id=eq.${id}&is_test=not.is.true${filtreOwner}&select=*&order=created_at.desc`),
-    PLAYER.db.selectAll(`commercial_doc_views?doc_id=eq.${id}&select=slug,event,page,max_page,seconds,session_id,at&order=at.asc`),
+    PLAYER.db.selectAll(`commercial_doc_views?doc_id=eq.${id}&select=slug,event,page,max_page,seconds,session_id,at&at=gte.${enc(depuisFenetre())}&order=at.asc`),
   ]);
   const shareList = Array.isArray(shares) ? shares : [];
   const viewList = Array.isArray(views) ? views : [];
@@ -160,7 +175,12 @@ async function listSharesForDoc(docId, owner) {
     if (mp > s.maxPage) s.maxPage = mp;
     s.seconds = Math.max(s.seconds, Number(v.seconds) || 0);
     if (v.session_id) s.sessions.add(v.session_id);
-    s.lastAt = v.at;
+    // ⚠️ UN MAXIMUM, PAS « LA DERNIÈRE LIGNE GAGNE ». `s.lastAt = v.at` n'était juste que TANT QUE la
+    // requête triait par `at.asc` — un couplage caché entre l'agrégation et l'ORDER BY, à trente
+    // lignes de distance. Quiconque aurait inversé le tri (pour garder le récent en cas de coupe)
+    // aurait transformé « dernière activité » en « première activité », sans qu'un seul test ne
+    // bouge. L'agrégation ne dépend plus de l'ordre : elle le calcule.
+    if (!s.lastAt || String(v.at) > String(s.lastAt)) s.lastAt = v.at;
   }
   const enriched = shareList.map((sh) => {
     const a = bySlug.get(sh.slug) || { opens: 0, maxPage: 0, seconds: 0, sessions: new Set(), lastAt: null };
@@ -186,7 +206,11 @@ async function listSharesForDoc(docId, owner) {
     maxPage: enriched.reduce((m, x) => Math.max(m, x.maxPage), 0),
     readers: reached.length, // sessions distinctes ayant tourné au moins une page
   };
-  return { shares: enriched, total, funnel };
+  // ⚠️ « PARLANT » : la réponse DIT ce qu'elle couvre. Une analytique bornée qui ne l'annonce pas
+  // est indiscernable d'une analytique complète — le lecteur y voit des chiffres définitifs. Le champ
+  // est présent même quand la fenêtre ne coupe rien (la purge à 13 mois arrive avant), pour que
+  // l'appelant n'ait jamais à déduire la couverture de l'ABSENCE d'un drapeau.
+  return { shares: enriched, total, funnel, fenetreMois: FENETRE_ANALYTIQUE_MOIS };
 }
 
 // Vue d'ensemble (tous documents) : stats agrégées par doc_id, pour les badges de la grille + le « top ».
@@ -197,7 +221,7 @@ async function overview() {
   // Borne glissante généreuse (24 mois) : ces tables d'événements grossissent sans fin ; sans filtre, le
   // scan intégral se dégrade avec le temps. 24 mois couvre tout l'historique utile pour la vue d'ensemble
   // (opens / lecteurs / dernière activité) sans changer les chiffres actuels. Filtre servi par l'index sur `at`.
-  const since = new Date(Date.now() - 24 * 30 * 24 * 60 * 60 * 1000).toISOString();
+  const since = depuisFenetre();
   const [views, internal] = await Promise.all([
     // PAGINÉ : au-delà de 1 000 lignes, PostgREST tronquait en silence — et comme le tri
     // est ascendant, c'est le RÉCENT qui disparaissait. Les consultations des trois dernières
@@ -237,7 +261,9 @@ async function overview() {
     if (v.event === "open") a.opens++;
     if (v.session_id) a.readers.add(v.session_id);
     a.maxPage = Math.max(a.maxPage, Number(v.page) || 0, Number(v.max_page) || 0);
-    a.lastAt = v.at;
+    // Même couplage caché que dans `listSharesForDoc`, et corrigé de la même façon : « dernière
+    // activité » se calcule, elle ne se déduit pas du tri de la requête.
+    if (!a.lastAt || String(v.at) > String(a.lastAt)) a.lastAt = v.at;
   }
   const intByDoc = new Map();
   for (const s of Array.isArray(internal) ? internal : []) {