discovery-media-player 0.1.128 → 0.1.129

package/docs/HOST-CONTRACT.md

@@ -76,12 +76,31 @@ The three `presence*` fields report what the host has **observed**, not what it
 | `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
-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.
+⚠️ **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 |
 |---|---|
@@ -96,14 +115,20 @@ when the long one is missing — i.e. exactly on the host that is behind and owe
 
 | `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 |
+| `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

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.128",
+  "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/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 : []) {