discovery-media-player 0.1.156 → 0.1.158

package/docs/HOST-CONTRACT.md

@@ -947,6 +947,20 @@ previous version claimed nothing. Four hours after the release, a host measured
 deployment caps, times out, paginates, or rewrites anything between us and your database, that
 limit is invisible from here and our arithmetic is probably wrong about it.
 
+⚠️ **If you sweep your own reads for this, sort them by what the value BECOMES, not by how many rows
+it holds.** This criterion is not ours: a host swept theirs, closed all of them, and reported that
+the row count had been the wrong axis the whole time. The expensive ones were the **aggregations** —
+a credit balance summed with a `reduce`, a read counter taken as `rows.length`, a visit tally
+incremented per row. A truncated sum does not look truncated: **it is wrong *and* plausible**, which
+is worse than the ceiling's usual symptom, a list that at least renders visibly stale. Their credit
+ledger stood at 503 rows and grows on every AI call — the invoice would have gone wrong before the
+table ever looked big enough to suspect.
+
+So the useful question about one of your reads is not *"could this exceed 1000?"* but **"is this
+value aggregated, or displayed?"** A displayed list degrades visibly. An aggregate degrades into a
+number someone will believe. Truncation you have decided to keep is fine and cheap to make honest —
+theirs kept one, bounded to 1000 and stated rather than assumed.
+
 **2. Something this card asserts that you can check against your own database.** Not "does it look
 right" — *does this number match what a query returns right now*. The purge card is the obvious one:
 `vide: true` is what authorises dropping a column, so a wrong `true` is expensive and a wrong `0`
@@ -991,6 +1005,80 @@ measurement came from rather than only what it said.
 The two kinds want opposite things from us: a debt should be chased, a structural limit should be
 written down and stopped being asked about.
 
+⚠️ **And there is a third kind, which we proposed as a false choice and a host corrected.** We asked
+another host to sort two backup figures — the PITR window, and the age of the oldest snapshot — into
+debt or structural limit. Their answer was neither, and the distinction is operational rather than
+pedantic:
+
+- **Not measurable by a session.** Checked against two independent toolsets — a second host's and
+  their own — neither the platform API nor the MCP tools expose either figure. The one tool with a
+  near-enough name restores a *paused* project.
+- **Measurable by a human.** An authenticated dashboard session displays both.
+
+So it is a debt whose payer is *necessarily a person*, and that is what makes it its own kind: it
+behaves like a structural limit toward every automated agent (chasing it changes nothing, no session
+will ever produce it), and like a debt toward the installation (someone can pay it, and until they
+do, the purge is not datable end to end). Their own phrasing, which we adopt: *"no session can
+render them; a human can, and until one has, the purge is not datable end to end."* They had raised
+it with theirs four times.
+
+The practical consequence for us is a rule about **who we are asking**, which we had never written:
+a question a host cannot answer with the tools they run on is not answered by asking again. Either
+it reaches a person, or it should be recorded and dropped.
+
+⚠️ **Where the substitution seam is, because a host asked and the answer was not written anywhere.**
+Their question came from their own defect: they had written a pagination helper after an incident,
+with its reason at the top, and it was called *nowhere*. The cause turned up only when they tried to
+use it — it called the **local binding** of their database client, while their benches replace the
+**export**, so adopting it broke the very bench that covered it. Their sentence is the part worth
+keeping: *"nobody writes «I don't use it because it breaks my doubles» — you give up in silence."*
+A non-substitutable helper produces no red, no complaint, no trace. It produces an absence of use,
+which nothing distinguishes from a need that never existed.
+
+Asked of us, the answer has two halves and only one of them is a promise:
+
+- **The injected context is substitutable, and that is the seam.** Every call reads `PLAYER.<member>`
+  at the moment it fires; nothing captures it into a local binding at module load, before you have
+  injected anything. Measured on 2026-09-05 across `server/` and `context/`: **144 calls, 0
+  captures.** Your double of `db.request` is the one that runs. `tools/couture-substituable.mjs`
+  now refuses a capture, so this stays true rather than happening to be true today.
+- **Our exports are not substitutable among themselves, and we do not promise they are.** Same date,
+  same zones: **64 of 75 exported names are also called internally through their local binding.**
+  If you stub `getShareBySlug` on the module we export and expect `overview()` to see your stub, it
+  will not. That is ordinary CommonJS and we are not changing 64 call sites for it — but you would
+  have discovered it the expensive way, so it is written here instead.
+
+Bring us the seam you need and cannot get, rather than working around a missing one in silence.
+
+⚠️ **What every report must carry: the version you measured on.** One field, and it is the one we
+kept losing. `version` is already in the identity card — `GET /api/doc` serves it — so this costs
+you a copy-paste and nothing else: *"measured on 0.1.146"*, beside the shape and the count.
+
+This is here because a host showed that we had asked for the wrong thing. We had asked hosts to stay
+current, reasoning that we cannot act on a report we cannot reproduce. Their correction: **what we
+need is not that you are up to date, it is knowing which version the measurement came from** — and a
+stamped report from a host eleven releases behind is reproducible, while an unstamped one from a
+perfectly current host is not. We then measured this document: of twelve host findings recorded in
+it, **none** names the version it was measured on. Some of those hosts were current at the time. The
+information was lost when we wrote it down, and no amount of future alignment brings it back.
+
+So: **shape, count, version.** If the measurement spans an upgrade, say both. If you no longer know
+which version a past observation came from, say that too — *"measured some time before 0.1.150"* is
+worth more than a number we would have to guess at, and far more than silence.
+
+⚠️ **And name yourself inside the report, not just in how you send it.** Reports reach us through
+whatever channel carries them, and a channel can deliver the same message twice or put one host's
+text under another host's name — both happened to us in a single round, and we spent an exchange
+establishing who had said what instead of acting on it. Neither you nor we could tell from our own
+end; only the person relaying could, and they did. **One line of self-identification in the body
+costs nothing and survives any relay** — the same reasoning as the version stamp, applied to *who*
+rather than *what*.
+
+The consequence for us is worth stating too, since it is about how much we can claim to have heard:
+when a duplicate is resolved, the reading it seemed to provide does not turn up elsewhere. It leaves
+us with one fewer host heard from, and we would rather record that plainly than let a channel look
+wider than it is.
+
 **What not to send.** Shapes and counts, never contents. No row data, no reader IPs or User-Agents —
 those are the columns half this contract exists to get rid of — no keys, tokens, connection strings,
 or private hostnames. *"A table of ~1600 rows returned 1000"* is the whole of what we needed to fix
@@ -1001,8 +1089,61 @@ dated entry naming the case. That last part is deliberate and a host asked for i
 justification rots, a dated incident does not. In six months someone will read a field and ask why
 it exists, and the answer will name you.
 
+⚠️ **But that date is ours, and for a long time we mistook it for yours.** Every changelog section
+carries the day *we shipped the fix* — 155 out of 155, checked. None carries the version *you*
+measured on, and the two answer different questions: ours says when it was closed, yours says what
+the observation was of. We had that backwards long enough to ask hosts for the wrong thing, so it is
+worth stating plainly rather than quietly correcting: **the entries above this line are unstamped,
+and cannot be retro-stamped** — the versions they were measured on were never recorded and are not
+recoverable. Everything from here on carries the stamp you send.
+
 ## Versioning
 
 Semantic versioning on the package, independent of the `contract` number. Pin an **exact** version:
 the player and its hosts deploy separately, and a range brings in a version nobody decided to
 deploy, on a day someone ran `npm install` for another reason.
+
+⚠️ **When we say a release "changes nothing for you", check it from *your* version — ours is not
+yours.** The zone table in every Release compares the new version to **the one immediately before
+it**. That is our convenience, not your situation: a host two or three releases back is looking at a
+different diff, and theirs is the one that decides. A host caught this by redoing it — we had
+compared `0.1.156 → 0.1.157`; they were jumping from `0.1.155`, ran their own comparison, and got a
+third file we had not mentioned. Same conclusion in the end (no migrations, zero lines of code in
+`server/` once comments are excluded), **but reached on their span rather than on our word.**
+
+So take the reassurance as a starting point and not as a finding. The tarballs are public: `npm pack`
+both versions and `diff -rq` the two trees is a minute's work, and it is the only version of the
+question that is about your installation.
+
+⚠️ **We asked you to stay current. That was the wrong ask, and a host took it apart.** The previous
+version of this paragraph requested that hosts keep the pin no more than one release behind, on the
+grounds that *a report we cannot reproduce is a report we cannot act on.* The premise is right. The
+conclusion did not follow:
+
+> You are asking that hosts be up to date; what you need is to know **which version a measurement
+> was taken on**. They are not the same thing, and the second is strictly cheaper.
+
+They are exactly right, and the counter-example is decisive. A host eleven releases behind who
+writes *"measured on 0.1.146: the 1600-row table returned 1000"* has given us a reproducible report.
+A perfectly aligned host who writes *"it returns 1000"* has not — and we find out only on the day we
+try to replay it. **Alignment neither implies the stamp nor substitutes for it.**
+
+⚠️ **And it is measurable in this very document — which is how we know the drift was never the
+cause.** They counted twelve places where this contract reports a host's finding and found one
+carrying a version nearby. We re-measured rather than take it: of those twelve, **zero** carry the
+version the host measured on. The single dated line in this file stamps *our own* measurement of our
+own code, not anyone's report. Several of those findings came from hosts who were current at the
+time. **The information was lost in the writing, not in the deployment, and no future alignment
+restores it.**
+
+⚠️ **Worse: the ask had the shape of the bias we had just written against ourselves.** A request to
+stay aligned can only be honoured by hosts who answer us, and is invisible in hosts who have
+drifted — so the channel would have reported "hosts are aligned" because the aligned are the only
+ones we hear from. That is the instrumentation bias one level up, applied to cadence instead of
+yield. The host who named it also took the release anyway, which is why the correction is theirs and
+not a concession.
+
+**So the ask is now the stamp, and it is above, in what a report must carry.** Staying current keeps
+a smaller and separate value — you get fixes sooner, and a release that changes nothing for you
+costs nothing to take — but it is no longer presented as what makes your reports usable. It never
+was.

package/package.json

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