discovery-media-player 0.1.167 → 0.1.169

package/docs/HOST-CONTRACT.md

@@ -182,10 +182,10 @@ these numbers from their side.
 | `fenetreS` | seconds this process has been running — **the window every total below was counted over** |
 | `seauxMs` | the bucket ladder the percentiles are read off, published **with** the numbers |
 | `familles` | **the denominator of `routes`** — every family this build measures, whether or not it was exercised. It does not move with traffic; that is what makes it a denominator |
-| `routes` | one entry per family of work — `document`, `presentation`, `action`, `fichier`, `carte`, `autre`. Families absent from the object were never exercised in this process |
+| `routes` | one entry per family of work — `document`, `presentation`, `action`, `fichier`, `carte`, `autre`. Families absent from the object were never exercised in this process. ⚠️ **`familles` is the scale, `routes` is the measure: `familles` never varies; what was seen is in `routes`.** A host displayed the scale as the measure for a whole day — "6 familles", permanently, on an instance that had just restarted — because nothing on the card said which of the two was which (STUDIO, 14/09) |
 | `base` | the same shape, for calls through the `db` capability **you** supply — measured at the seam, so it covers every call, including ones nobody has written yet |
 | `statuts` | responses by class: `ok` (<400), `refus4xx`, `debit429`, `occupe503`, `erreur5xx` |
-| `memoireMio` | `rss`, `heap` (heap used), `tampons` (`arrayBuffers`) in MiB, read at the moment of the request. ⚠️ **Half a number**: it is only judicable against the memory ceiling of the process, which the player does not know and no platform serves the same way — on Lambda-based functions (Vercel included) read `AWS_LAMBDA_FUNCTION_MEMORY_SIZE`; in a container, the cgroup limit. A host spent half a day finding that its project API, its logs and its `vercel.json` all left it out (14/09). Display the ceiling beside the RSS, or the RSS says nothing about the relay ceiling you can afford |
+| `memoireMio` | `rss`, `heap` (heap used), `tampons` (`arrayBuffers`) in MiB, read at the moment of the request. ⚠️ **Half a number**: it is only judicable against the memory ceiling of the process, which the player does not know and no platform serves the same way — on Lambda-based functions (Vercel included) read `AWS_LAMBDA_FUNCTION_MEMORY_SIZE`; in a container, the cgroup limit. A host spent half a day finding that its project API, its logs and its `vercel.json` all left it out (14/09). Display the ceiling beside the RSS, or the RSS says nothing about the relay ceiling you can afford. And the ceiling makes the RSS **comparable, not the question decidable**: whether 64 relays fit is settled only by a reading under load, never by a gauge read at rest (STUDIO, 14/09) |
 | `boucleMs` | event-loop **delay** — `moyen` and `p99` in ms, with `n` samples and the sampler's `resolutionMs` |
 
 ⚠️ **A percentile over buckets is a bound, not a value.** `p95sousMs: 250` reads *"95% of calls
@@ -284,6 +284,15 @@ by the card, structured and dated, and never by a search through logs for `relai
 log line stays for diagnosis, the card is the way to *notice*. Process-local like everything on this
 card, and **never reset by `init`**, exactly like the counter of open relays.
 
+⚠️ **A zero is informative only beside the traffic that could have produced the event — `fenetreS`
+alone is not enough.** A host read `total: 0` over a 999-second window and showed *no relay
+refused*, *no saturated read* in green; over that window `mesures.routes` carried only `action`
+(3 calls) — not one file, not one presentation read, so neither counter had had a single occasion
+(STUDIO, 14/09). Read `mesures.routes.fichier.n` next to `relaisRefuses` and
+`mesures.routes.presentation.n` next to `lectureSaturee` — the families are `familleDe`'s, not
+guessed — and the timer wraps the whole handler, so `n` counts the refused calls too: it is the
+denominator you want. Both hosts' cards now say *no occasion yet* instead of green.
+
 ⚠️ **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
@@ -647,7 +656,21 @@ context shipped in this package already implements it** — if you build your co
 `discovery-media-player/context/standalone`, you get it on your next upgrade and there is nothing
 to decide or write. This section is for a host that implements the `db` capability itself. A host
 asked which of the two it was, and the answer was missing from this page: *"the two look alike in
-your code and not at all alike at your hosts."* If your `db` capability
+your code and not at all alike at your hosts."* ⚠️ **The same line decides which zone of a release
+reaches you, and it is read per capability, not per host.** Three forms. A host that runs
+`context/standalone` as is (ADV does, unchanged since August — **read in its public wiring
+repository, not taken from a message**: for a host whose wiring is public, the file is the source,
+and a replaced context would show in a commit before it showed in a message) executes every change to the `context`
+zone — the environment pass-through, the journal helper — and its `errors.capture` is the player's
+own. A host that **composes** its context from `createStandaloneContext` and replaces some
+capabilities (the Vercel example in this repository does: `identity` and `branding` are its own,
+everything else inherited) is reached by every change to a capability it inherits, and by none to a
+capability it replaced; `creerLimites` is exported for exactly that host. A host whose context
+imports nothing from `context/` (STUDIO) is touched by `server/` only. That line was missing from
+what the player held about its hosts, and a release note told one of them a change to its own file
+was "without effect on your side" (14/09); the first version of this paragraph was binary, and an
+audit pointed at the repository's own example as the third case. Say your form once; it is the
+line the notes are written from. If your `db` capability
 exposes it, the player asks it first and publishes an **exact** count — no bound, no `tronque`, and
 no rows transported at all. If it is absent, everything above still applies unchanged: the bounded
 read with its cursor probe. **That fallback is the whole design.** Third-party hosts implement this
@@ -888,7 +911,12 @@ per process before answering **503 busy** to everyone. A database call that hang
 "slow", it is an availability incident for the whole instance — the exact mechanism an audit
 reproduced inside the test suite with a never-settling promise (13/09). Time out your own calls
 (the standalone context bounds its own with `AbortSignal`), and never return a promise you cannot
-guarantee will settle.
+guarantee will settle. ⚠️ **The bound must cover the body, not only the headers.** `fetch` resolves
+as soon as the headers arrive; `response.text()` then hangs on a stream left open, so a timeout
+that stops at the headers bounds half the path. Pass the same `AbortSignal` to the fetch, which
+aborts the body read too (the standalone context does), and if you retry an abandoned call, retry a
+read only, never a write. A host (STUDIO, 13/09) found its own `db.request` bounded that way — at
+the headers — and rewrote it; the rule is theirs.
 
 **Your document-opening doors reappear.** A host has more than one place that opens a file, and new
 ones get written. Keep the list and hunt it periodically — and note that **your search criteria

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.167",
+  "version": "0.1.169",
   "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",
@@ -84,6 +84,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.11",
+    "ajv": "8.20.0",
     "axe-core": "^4.13.0",
     "dockerfile-ast": "0.7.1",
     "esbuild": "^0.28.2",

package/server/cache.js

@@ -85,6 +85,21 @@ function creerCache(options) {
   const entrees = new Map();
   let poidsTotal = 0;
   let nEnVol = 0;      // tenu à jour à chaque transition — compter la Map à la demande serait O(n)
+  // ⚠️ CE QUE LE CACHE A FAIT, PAS SEULEMENT CE QU'IL A REFUSÉ. `satures()` disait les refus ; rien ne
+  // disait combien de lectures avaient été servies de la mémoire, regroupées sur une production en
+  // vol, ou produites. L'artefact de charge (audit, 14/09) demande les trois et le pic en vol :
+  // sans eux, « le cache tient » est une phrase, pas une mesure. Compteurs de processus, comme tout
+  // ici : jamais remis à zéro, à lire en deltas.
+  let nServies = 0, nRegroupees = 0, nProduites = 0, picEnVol = 0;
+  // ⚠️ LES OBSERVATEURS DE FENÊTRE, ET POURQUOI ILS NE TOUCHENT PAS À L'ÉTAT DU CACHE. `picEnVol`
+  // est un maximum DEPUIS LE DÉMARRAGE : quand le rapport de charge le recopiait tel quel à côté de
+  // hits/misses/coalesced convertis en DELTAS, une position calme héritait du pic d'une position
+  // chargée et affirmait une concurrence qu'elle n'avait jamais vue. Remettre `picEnVol` à zéro
+  // entre deux positions serait pire : on modifierait le SYSTÈME MESURÉ pour arranger l'instrument,
+  // et le pic historique — qui a son utilité — disparaîtrait. Un observateur est donc un compteur
+  // SÉPARÉ, ouvert et refermé par qui mesure, sans que le cache change de comportement.
+  // Relevé par un audit externe (CODEX, 15/09).
+  const observateurs = new Set();
 
   const oublier = (k) => {
     const e = entrees.get(k);
@@ -127,7 +142,10 @@ function creerCache(options) {
       // qui décide : refuser d'abord ferait échouer des appelants que le regroupement pouvait servir
       // gratuitement — la saturation punirait alors la rafale légitime, exactement ce que ce cache
       // existe pour absorber. On ne refuse que ce qui coûterait une requête DE PLUS.
-      if (vue && (vue.enVol || vue.echeance > t)) return vue.promesse;
+      if (vue && (vue.enVol || vue.echeance > t)) {
+        if (vue.enVol) nRegroupees += 1; else nServies += 1;
+        return vue.promesse;
+      }
 
       if (nEnVol >= maxEnVol) {
         nSatures += 1;
@@ -143,6 +161,9 @@ function creerCache(options) {
       let placeRendue = false;
       const rendrePlace = () => { if (!placeRendue) { placeRendue = true; nEnVol -= 1; } };
       nEnVol += 1;
+      nProduites += 1;
+      if (nEnVol > picEnVol) picEnVol = nEnVol;
+      for (const o of observateurs) if (nEnVol > o.pic) o.pic = nEnVol;
       // ⚠️ L'ÉCHÉANCE PART DE LA RÉSOLUTION, PAS DE LA DEMANDE. Posée à la demande, elle expirait
       // AVANT que la production ne réponde dès que celle-ci dépassait le TTL — et le regroupement ne
       // servait alors plus à rien pour exactement les producteurs lents, les seuls qu'il valait la
@@ -193,6 +214,23 @@ function creerCache(options) {
     poids: () => poidsTotal,
     /** Demandes actuellement en vol — ce que le plafond d'admission borne. */
     enVol: () => nEnVol,
+    /**
+     * Ce que ce cache a fait depuis le démarrage du processus : `hits` servies de la mémoire,
+     * `coalesced` regroupées sur une production déjà en vol, `misses` produites, `peakInFlight` le
+     * plus grand nombre de productions simultanées. Les refus sont dans `satures()`.
+     */
+    compteurs: () => ({ hits: nServies, coalesced: nRegroupees, misses: nProduites, peakInFlight: picEnVol }),
+    /**
+     * Ouvre une fenêtre d'observation du pic en vol : `{ pic(), fermer() }`. Le cache n'est pas
+     * modifié — ni remis à zéro, ni ralenti ; seul un compteur parallèle suit les productions
+     * simultanées TANT QUE la fenêtre est ouverte. `fermer()` est impératif : un observateur oublié
+     * survit au relevé qui l'a demandé.
+     */
+    observerEnVol: () => {
+      const o = { pic: nEnVol };
+      observateurs.add(o);
+      return { pic: () => o.pic, fermer: () => observateurs.delete(o) };
+    },
     /**
      * Ce que le plafond a refusé depuis le démarrage de ce processus.
      *

package/server/handler.js

@@ -1249,6 +1249,19 @@ module.exports = { __contexte: () => PLAYER, handler, init, TIERS, POLITIQUE_PER
   // ⚠️ COUTURE DE BANC, PAS D'API : le cache de lecture est global au module, et un banc qui laisse des
   // lectures en vol contamine le suivant (128 promesses éternelles, 503 partout — trouvé par un audit
   // externe sous mélange, graine 20260913). Un banc doit pouvoir VÉRIFIER qu'il rend le cache vide.
-  __cacheLecture: cacheLecture };
+  __cacheLecture: cacheLecture,
+  // ⚠️ COUTURE DE MESURE : LIRE LES COMPTEURS SANS LES INCRÉMENTER. Le rapport de charge relevait
+  // ces grandeurs par un `GET ?contract=1` — c'est-à-dire par une requête qui TRAVERSE le handler et
+  // incrémente `mesures.statuts.ok` au passage. Le delta d'une fenêtre de 1 000 requêtes valait donc
+  // 1 001, systématiquement, et pour chaque position : l'observateur se comptait lui-même. Une
+  // soustraction cachée aurait corrigé le chiffre en aggravant le problème — un instrument qui se
+  // retranche discrètement est plus difficile à auditer qu'un instrument faux. La couture rend l'état
+  // tel qu'il est, sans le modifier ; ce que la fenêtre contient d'autre que la charge se DIT, dans
+  // `counters.observerOverheadRequests`. Défaut relevé par un audit externe (CODEX, 15/09).
+  __compteursSansObserver: () => ({
+    lectureSaturee: { total: cacheLecture.satures().total },
+    relaisRefuses: { total: relaisRefusesTotal },
+    mesures: mesures.relever(),
+  }) };
 
 // redeploy: forcer le build production (Vercel a sauté la prod du merge #463 — wording re-partage).