discovery-media-player 0.1.127 → 0.1.128

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,6 +74,7 @@ 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) |
+| `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`.** It is a *report of execution*: on an
 instance where nothing is running it says `inconnu`, which means *nobody looked* — not *the migration
@@ -87,9 +89,26 @@ 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 |
+| `absente` | `0019` is missing: **nothing breaks**, a heartbeat costs **3** round trips instead of 2 (about 30 ops/s instead of 20 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.
+
+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/package.json

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

@@ -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 :