ci: IS-572: re-sync ported Cloudflare Workers pipeline files with rollingclaude/cf-port-circinus

The category-1 files in this port are byte-identical copies from `rolling`.
`rolling` has since moved: [vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
merged as `3a1c6c30`, thirteen rounds of hardening on exactly these files.

Re-take all 14 category-1 paths from `origin/rolling` via
`git checkout origin/rolling -- <paths>`, so byte-identity holds by
construction rather than by hand-editing:

  .github/workflows/docs-build.yml
  scripts/docs_gates/{gates,parity,smoke,test_gates,test_parity,test_smoke}.py
  workers/.gitignore
  workers/apex/src/{index,special,uagate}.ts
  workers/apex/test/{router,uagate}.test.ts
  workers/apex/ua-policy.json

Thirteen of the fourteen carry
[vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
exactly — the pre-change tree was byte-identical to `3a1c6c30^` for those
paths. `workers/.gitignore` additionally picks up the one-line `test-results/`
entry from
[vyos-documentation#2212](https://github.com/vyos/vyos-documentation/pull/2212);
inert on circinus, since only the deliberately-unported `apex-deploy.yml`
writes that directory.

Deliberate exclusions are unchanged: `docs-canary-qa.yml` (cron runs on the
default branch only, so it is not ported even though
[vyos-documentation#2209](https://github.com/vyos/vyos-documentation/pull/2209)
touched it on `rolling`), `apex-deploy.yml`, and the `docs-preview-*`
workflows. `docs/conf.py` stays hand-merged and circinus-specific, with its
ReadTheDocs fallback intact.

🤖 Generated by [robots](https://vyos.io)

1 files changed, 420 insertions, 18 deletions

diff --git a/workers/apex/src/index.ts b/workers/apex/src/index.ts
index 278794e2..f97b4bc5 100644
--- a/workers/apex/src/index.ts
+++ b/workers/apex/src/index.ts
@@ -47,6 +47,263 @@ function apexHeaders(resp: Response, env: ApexEnv, cacheClass: string = DEFAULT_
   return out;
 }
 
+// R2's `R2Range` is a three-shape union — `{offset, length?}`, `{length}` (offset implicitly 0)
+// and `{suffix}` (the trailing N bytes) — so `"offset" in range` is NOT a safe way to read it:
+// the two offset-less shapes would fall through to the full-object 200 branch and be served
+// with a Content-Length claiming the whole object while the body held only a slice. workerd is
+// observed to normalize every shape to `{offset, length}` before it reaches us, but the type
+// admits the others, so resolve all three to concrete byte bounds, clamped to the object size.
+// Exported for direct unit testing.
+export function resolveRange(
+  range: { offset?: number; length?: number; suffix?: number },
+  size: number,
+): { start: number; length: number } {
+  if (typeof range.suffix === "number") {
+    const suffix = Math.min(Math.max(range.suffix, 0), size); // a suffix past the start is the whole object
+    return { start: size - suffix, length: suffix };
+  }
+  const start = Math.min(Math.max(range.offset ?? 0, 0), size);
+  // The trailing Math.max(_, 0) keeps the documented "clamped to the object size" contract
+  // total: without it a negative `range.length` would pass straight through Math.min and
+  // yield a negative length (and so a negative Content-Length). A real R2 binding cannot
+  // produce that — see classifyRangeHeader's note on observed R2 behaviour — but this
+  // function is exported and unit-tested as a standalone utility over the R2Range union, so
+  // it should not have a documented invariant its own signature can violate. Deliberately
+  // NOT guarding non-finite inputs: NaN bounds are unreachable from the binding and the
+  // guard would be untestable-in-anger dead weight.
+  const length = Math.max(Math.min(range.length ?? size - start, size - start), 0);
+  return { start, length };
+}
+
+// A single `bytes=` range-spec. Anything with a comma is a multi-range and deliberately
+// fails to match. The whitespace class is `\s`, which is DELIBERATELY wider than the ` `
+// (ASCII space) that R2's own parser accepts — see classifyRangeHeader's contract note on
+// why the two grammars are allowed to disagree.
+const SINGLE_BYTE_RANGE = /^\s*bytes\s*=\s*(\d*)\s*-\s*(\d*)\s*$/i;
+
+/**
+ * Numeric comparison of two non-empty digit strings, without going through Number().
+ *
+ * A range-spec's positions are unbounded digit strings, and Number() silently rounds
+ * anything above 2^53: `Number("9007199254740993") === Number("9007199254740992")`, which
+ * collapsed `bytes=9007199254740993-9007199254740992` — an invalid spec (last < first)
+ * that §14.1.2 says to IGNORE, so 200 — into an apparently-valid one that then read as
+ * unsatisfiable and answered 416. Comparing normalised digit strings by length and then
+ * lexically is exact at every magnitude.
+ */
+function cmpDigits(a: string, b: string): number {
+  const x = a.replace(/^0+(?=\d)/, "");
+  const y = b.replace(/^0+(?=\d)/, "");
+  if (x.length !== y.length) return x.length - y.length;
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+
+export type RangeIntent =
+  | { kind: "ignored" }
+  | { kind: "unsatisfiable" }
+  | { kind: "single"; start: number; length: number };
+
+/**
+ * What the client's Range header ASKS FOR, judged against the representation length.
+ *
+ * This exists because R2 does not tell us. Probed against a real R2 binding under
+ * vitest-pool-workers, `get(key, {range: <Headers>})` signals "I ignored your Range" by
+ * returning the WHOLE object with `range = {offset: 0, length: size}` — the byte-for-byte
+ * same shape it returns for a legitimately-satisfied whole-object range like `bytes=0-`.
+ * It does this for every unsatisfiable spec (`bytes=10-` / `bytes=99-` / `bytes=-0` on a
+ * 10-byte object), every malformed one (`bytes=abc`, `bytes=-`, `bytes=5-2`), multi-ranges
+ * (`bytes=0-1,4-5`) and unknown units (`items=0-5`). It does NOT throw for any of them and
+ * it never returns a zero/negative length except for a genuinely zero-length object.
+ * (The object-literal form `get(key, {range: {offset: 99}})` DOES throw
+ * "The requested range is not satisfiable (10039)" — but this Worker passes Headers, so
+ * that path is unreachable here.)
+ *
+ * Trusting `obj.range` alone therefore answered `Range: bytes=99-` with
+ * `206 + Content-Range: bytes 0-9/10` and the FULL body — a 206 that does not correspond to
+ * the request (RFC 9110 §15.3.7). That is actively dangerous for the resuming downloader
+ * this range forwarding exists to serve: a client resuming at byte 99 would append bytes
+ * 0-9 to its partial file and silently corrupt it. Re-deriving intent from the client's own
+ * header is the only way to separate the three cases.
+ *
+ * Satisfiability follows RFC 9110 §14.1.2 verbatim: an int-range is satisfiable iff
+ * first-pos < length; a suffix-range iff suffix-length is non-zero (so on a zero-length
+ * representation, a non-zero suffix-range is the ONLY satisfiable form). An invalid spec
+ * (last-pos < first-pos) MUST be ignored rather than rejected, hence "ignored", not
+ * "unsatisfiable".
+ *
+ * The `single` verdict carries the CONCRETE byte bounds the client asked for, clamped the
+ * way §14.1.2 clamps them. That is what makes this classifier safe to disagree with R2's
+ * parser. The two grammars are not identical and cannot be kept identical: R2's accepts
+ * only ASCII space around the tokens (miniflare's `/^ *(\d+)? *- *(\d+)? *$/`) while this
+ * one accepts `\s`, so `Range: bytes=2<TAB>-<TAB>4` parses here and is ignored there. When
+ * a caller compares these bounds against the bytes R2 actually handed back, any such
+ * divergence — this one, or the next one a parser change introduces — degrades to a plain
+ * 200 instead of a 206 whose Content-Range describes a body the client did not ask for.
+ * Chasing byte-for-byte grammar parity would put the guarantee back in the hands of two
+ * regexes staying in sync, which is the coupling that produced the bug.
+ */
+export function classifyRangeHeader(header: string, size: number): RangeIntent {
+  const m = SINGLE_BYTE_RANGE.exec(header);
+  if (!m) return { kind: "ignored" }; // multi-range, unknown unit, or unparseable
+  const [, firstRaw, lastRaw] = m;
+  if (firstRaw === "") {
+    if (lastRaw === "") return { kind: "ignored" }; // bare "bytes=-" is malformed
+    // §14.1.2: suffix-length 0 is unsatisfiable; a suffix past the start is the whole object.
+    if (cmpDigits(lastRaw, "0") <= 0) return { kind: "unsatisfiable" };
+    const suffix = Math.min(Number(lastRaw), size);
+    return { kind: "single", start: size - suffix, length: suffix };
+  }
+  // §14.1.2: an invalid spec (last-pos < first-pos) is ignored, not rejected.
+  if (lastRaw !== "" && cmpDigits(lastRaw, firstRaw) < 0) return { kind: "ignored" };
+  if (cmpDigits(firstRaw, String(size)) >= 0) return { kind: "unsatisfiable" };
+  const first = Number(firstRaw); // < size, so within safe-integer range
+  const last = lastRaw === "" ? size - 1 : Math.min(Number(lastRaw), size - 1);
+  return { kind: "single", start: first, length: last - first + 1 };
+}
+
+/** A quoted entity-tag list (`"a", W/"b"`) or `*`, compared per RFC 9110 §8.8.3.2. */
+function etagListMatches(list: string, etag: string, compare: "strong" | "weak"): boolean {
+  const items = list.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  if (items.includes("*")) return true; // "*" matches iff a representation exists — one does
+  const weaken = (t: string) => t.replace(/^W\//, "");
+  // Strong comparison: neither side may be weak (§8.8.3.2).
+  if (compare === "strong" && etag.startsWith("W/")) return false;
+  return items.some((t) =>
+    compare === "strong" ? t === etag : weaken(t) === weaken(etag),
+  );
+}
+
+/**
+ * `uploaded <= <HTTP-date>`, at seconds granularity, or null when the date is unparseable
+ * (§13.1.3: an invalid date MUST be ignored, which callers map to "precondition passes").
+ * Seconds granularity matches R2's own comparison, which the Headers form of `onlyIf`
+ * selects — evaluating at millisecond precision here would disagree with the binding that
+ * produced the failure we are trying to name.
+ */
+function uploadedAtOrBefore(uploaded: Date | undefined, httpDate: string): boolean | null {
+  const at = Date.parse(httpDate);
+  if (Number.isNaN(at) || !uploaded) return null;
+  return Math.floor(uploaded.getTime() / 1000) <= Math.floor(at / 1000);
+}
+
+/**
+ * The conditional headers R2 is allowed to see, filtered to those RFC 9110 §13.2.2 says
+ * actually apply to THIS request.
+ *
+ * R2 ANDs together every validator it is handed; §13.2.2 instead defines a precedence in
+ * which a lower-ranked validator is not evaluated at all. Forwarding `request.headers`
+ * wholesale therefore let R2 fail a request on a validator the RFC says to ignore — most
+ * visibly `If-Modified-Since` on a non-GET/HEAD method, which §13.2.2 step 4 does not
+ * evaluate, but which R2 evaluated anyway and answered with a body-less object that this
+ * Worker could only turn into a 412. Filtering at the source means a body-less result now
+ * always corresponds to a precondition that genuinely applies.
+ *
+ * The METHOD decides this before any header does. §13.2.1: "a server MUST ignore the
+ * conditional request header fields defined by this specification when received with a
+ * request method that does not involve the selection or modification of a selected
+ * representation, such as CONNECT, OPTIONS, or TRACE." Filtering by validator applicability
+ * alone still handed those methods' conditionals to R2, so an OPTIONS carrying a stale
+ * `If-Match` a client had left lying around was refused 412 where the same request without
+ * it succeeded. Returning an empty set here is what "ignore" means at this layer: R2 is
+ * given nothing to evaluate, so it cannot answer body-less, so preconditionStatus() — which
+ * is only ever reached from a body-less result — is unreachable for these methods too.
+ */
+function applicablePreconditions(h: Headers, method: string): Headers {
+  const out = new Headers();
+  if (method === "OPTIONS" || method === "TRACE" || method === "CONNECT") return out;
+  const isGetOrHead = method === "GET" || method === "HEAD";
+  const ifMatch = h.get("if-match");
+  const ifNoneMatch = h.get("if-none-match");
+  if (ifMatch !== null) out.set("if-match", ifMatch);
+  else {
+    const ius = h.get("if-unmodified-since"); // §13.2.2 step 2: only when If-Match is absent
+    if (ius !== null) out.set("if-unmodified-since", ius);
+  }
+  if (ifNoneMatch !== null) out.set("if-none-match", ifNoneMatch);
+  else if (isGetOrHead) {
+    const ims = h.get("if-modified-since"); // step 4: only when If-None-Match is absent, GET/HEAD only
+    if (ims !== null) out.set("if-modified-since", ims);
+  }
+  return out;
+}
+
+/**
+ * Which status a FAILED `onlyIf` owes the client, decided by re-evaluating the request's
+ * conditionals against the object's own validators in RFC 9110 §13.2.2 order.
+ *
+ * R2 reports THAT a precondition failed and never WHICH one. Inferring from header
+ * PRESENCE cannot be right in both directions, which is how `If-Match: "x"` +
+ * `If-None-Match: "x"` on a matching object — If-Match satisfied, If-None-Match failed,
+ * so §13.1.2 owes a 304 — came back 412 purely because an If-Match header was present.
+ * Evaluating the validators removes the guess: presence selects which check runs, the
+ * comparison decides the answer.
+ */
+export function preconditionStatus(
+  h: Headers, isGetOrHead: boolean, etag: string, uploaded: Date | undefined,
+): 304 | 412 {
+  const ifMatch = h.get("if-match");
+  if (ifMatch !== null) {
+    if (!etagListMatches(ifMatch, etag, "strong")) return 412; // §13.2.2 step 1
+  } else {
+    const ius = h.get("if-unmodified-since"); // step 2
+    if (ius !== null && uploadedAtOrBefore(uploaded, ius) === false) return 412;
+  }
+  const ifNoneMatch = h.get("if-none-match");
+  if (ifNoneMatch !== null) {
+    // §13.1.2: a failed If-None-Match is 304 for GET/HEAD and 412 for every other method.
+    if (etagListMatches(ifNoneMatch, etag, "weak")) return isGetOrHead ? 304 : 412;
+  } else if (isGetOrHead) {
+    const ims = h.get("if-modified-since"); // step 4
+    if (ims !== null && uploadedAtOrBefore(uploaded, ims) === true) return 304;
+  }
+  // R2 refused for a reason this evaluation could not reproduce (a validator comparison
+  // that differs at the margins, say). 412 is the safe answer: a 304 would assert a cache
+  // validity we have not established.
+  return 412;
+}
+
+/**
+ * RFC 9110 §13.1.5 If-Range: does the client's validator still describe this object?
+ *
+ * R2 cannot answer this — its `R2Conditional` carries only etagMatches /
+ * etagDoesNotMatch / uploadedBefore / uploadedAfter, so an `If-Range` in the forwarded
+ * Headers is silently dropped and the range is applied unconditionally. For an object
+ * whose ETag has moved on, that answered `Range: bytes=100-` + `If-Range: "old"` with
+ * bytes 100+ of the NEW representation under a 206 — a resuming downloader then appends
+ * the new tail to its old prefix and silently corrupts the file, which is the precise
+ * failure this range forwarding exists to avoid.
+ *
+ * §13.1.5 requires a STRONG validator, so a weak entity-tag never matches. The date form
+ * likewise never matches here: it must compare against Last-Modified, and this Worker
+ * does not emit one, so no client can hold a date validator for this resource that we
+ * could honour — treating it as a mismatch (serve the complete representation) is both
+ * correct and the safe direction.
+ */
+function ifRangeMatches(value: string, etag: string): boolean {
+  const v = value.trim();
+  if (!v.startsWith('"')) return false; // weak tag or HTTP-date → not a strong match
+  return etagListMatches(v, etag, "strong");
+}
+
+/**
+ * Abandon a body stream this Worker has decided not to send.
+ *
+ * R2 hands back a body on paths whose response carries none. An unsatisfiable Range gets
+ * the COMPLETE object (29.2 MiB for the 1.3 PDF) and is answered 416 with a null body; a
+ * stale `If-Range` gets the sliced range and is answered from a re-read. Dropping the
+ * reference leaves the stream open until GC collects it, holding the connection; cancelling
+ * releases it now and aborts the transfer rather than draining it. Failures are swallowed —
+ * this is cleanup on a path whose response is already decided, and a stream that is already
+ * closed or errored is exactly the state we wanted.
+ */
+async function discardBody(body: ReadableStream | null | undefined): Promise<void> {
+  try {
+    await body?.cancel();
+  } catch {
+    /* already closed or errored — nothing left to release */
+  }
+}
+
 async function themed(env: ApexEnv, status: 404 | 503): Promise<Response> {
   const page = await env.ASSETS.fetch(new Request(`https://apex.internal/${status}.html`));
   return apexHeaders(new Response(page.body, { status, headers: { "content-type": "text/html; charset=utf-8" } }), env);
@@ -78,14 +335,24 @@ export default {
         console.log(JSON.stringify({ event: "binding-missing", binding: "DOCS_PDFS" }));
         return themed(env, 503);
       }
+      const method = request.method.toUpperCase();
+      const isGetOrHead = method === "GET" || method === "HEAD";
+      // §14.2: "GET is the only method for which range handling is defined" — a Range on
+      // any other method MUST be ignored. Reading it as null here suppresses the whole
+      // partial-content path in one place: R2 is never asked to slice, and the 206/416
+      // branches below are unreachable. Gating only the R2 forward would leave the
+      // response side still seeing a Range header and answering a HEAD or a POST with a
+      // 416 or a Content-Range.
+      const rangeHeader = method === "GET" ? request.headers.get("range") : null;
+      const onlyIf = applicablePreconditions(request.headers, method);
+
       let raw: R2ObjectBody | R2Object | null;
       try {
-        // Forward Range + conditional (If-None-Match/If-Match/If-Modified-Since) headers
-        // straight through to R2 so a resumed download or a client with a fresh cached
-        // copy doesn't have to re-pull the full 29.2 MiB object.
+        // Forward Range + the APPLICABLE conditionals so a resumed download or a client
+        // with a fresh cached copy doesn't have to re-pull the full 29.2 MiB object.
         raw = await bucket.get(pdfVersion.pdf_r2_key!, {
-          range: request.headers,
-          onlyIf: request.headers,
+          ...(rangeHeader !== null ? { range: request.headers } : {}),
+          onlyIf,
         });
       } catch (e) {
         console.log(JSON.stringify({ event: "binding-error", binding: "DOCS_PDFS", error: String(e) }));
@@ -102,25 +369,160 @@ export default {
         "accept-ranges": "bytes",
       };
 
-      // A satisfied onlyIf precondition (e.g. If-None-Match matched the R2 object's current
-      // ETag) makes R2 hand back a body-less R2Object — just the validators, no content.
+      // A FAILED onlyIf precondition makes R2 hand back a body-less R2Object — just the
+      // validators, no content — and never says which validator failed. Because `onlyIf`
+      // was filtered to the conditionals §13.2.2 actually applies to this request, a
+      // body-less result here always means a precondition that genuinely applies failed;
+      // preconditionStatus() re-evaluates them against the object's own validators, in
+      // §13.2.2 order, to decide between 304 and 412.
       if (!("body" in raw) || !raw.body) {
-        return apexHeaders(new Response(null, { status: 304, headers: pdfHeaders }), env, pdfCacheClass);
+        const status = preconditionStatus(
+          request.headers, isGetOrHead, raw.httpEtag, raw.uploaded);
+        return apexHeaders(new Response(null, { status, headers: pdfHeaders }), env, pdfCacheClass);
       }
-      const obj = raw as R2ObjectBody;
+      let obj = raw as R2ObjectBody;
       pdfHeaders["content-type"] = "application/pdf";
 
-      // A satisfied Range request — R2 echoes the actually-served byte range on `obj.range`;
-      // its absence means either no Range header was sent or R2 served the full object.
-      const range = obj.range;
-      if (range && "offset" in range) {
-        const start = range.offset ?? 0;
-        const length = range.length ?? obj.size - start;
-        pdfHeaders["content-range"] = `bytes ${start}-${start + length - 1}/${obj.size}`;
-        pdfHeaders["content-length"] = String(length);
-        return apexHeaders(new Response(obj.body, { status: 206, headers: pdfHeaders }), env, pdfCacheClass);
+      // §13.1.5 If-Range, which R2 cannot evaluate (see ifRangeMatches). A failed validator
+      // means the client's partial copy is stale, so the Range is ignored ENTIRELY and the
+      // complete representation is served — including for a spec that would otherwise be
+      // unsatisfiable, since the 416 branch below must not fire on a range we have decided
+      // not to honour. R2 has already applied the range at this point, so the whole object
+      // has to be re-read; that costs one extra R2 read on the rare stale-resume path and
+      // nothing at all on the common one.
+      //
+      // The re-read carries the SAME `onlyIf`. §13.2.1 requires preconditions to hold for the
+      // representation ultimately selected, and the two reads need not see one object: a bare
+      // re-get answered `Range` + stale `If-Range` + `If-Match: "A"` with a 200 carrying
+      // object B, whose ETag the client had explicitly excluded, whenever the key was
+      // rewritten in between. That rewrite is not hypothetical — the legacy snapshot repo's
+      // deploy workflow re-uploads this exact key on its `force_pdf_refresh` input. Re-sending
+      // the conditionals ties the verdict to the bytes actually served, because R2 evaluates
+      // `onlyIf` against the very object it returns; the body-less outcome that produces is
+      // not a gap in this path but the correct answer, resolved by preconditionStatus()
+      // exactly as on the first read. When no conditionals were sent, `onlyIf` is empty and a
+      // body-less result cannot occur, so the common path is untouched.
+      //
+      // A head() before the get() would also expose the validators, and would avoid opening
+      // this slice stream at all — but it would put a second round-trip on the path where
+      // If-Range MATCHES, which is the normal resumed download, in exchange for tidying the
+      // rare one where it does not. It would also widen the window this shape keeps narrow:
+      // the object whose validators decide the verdict is the one R2 returns from the same
+      // call. So the get-then-re-read stays, and the slice we are abandoning is cancelled
+      // rather than left to GC.
+      const ifRange = rangeHeader !== null ? request.headers.get("if-range") : null;
+      let rangeApplies = rangeHeader !== null;
+      if (ifRange !== null && !ifRangeMatches(ifRange, obj.httpEtag)) {
+        rangeApplies = false;
+        await discardBody(obj.body);
+        let full: R2ObjectBody | R2Object | null;
+        try {
+          full = await bucket.get(pdfVersion.pdf_r2_key!, { onlyIf });
+        } catch (e) {
+          console.log(JSON.stringify({ event: "binding-error", binding: "DOCS_PDFS", error: String(e) }));
+          return themed(env, 503);
+        }
+        if (!full) return themed(env, 404); // deleted between the two reads
+        if (!("body" in full) || !full.body) {
+          // The key was rewritten between the two reads and the request's preconditions do
+          // not hold for the new representation. Same treatment as a first-read failure, on
+          // the new object's validators — never the old ones, which describe a representation
+          // this response is not about.
+          const status = preconditionStatus(
+            request.headers, isGetOrHead, full.httpEtag, full.uploaded);
+          return apexHeaders(new Response(null, {
+            status, headers: { etag: full.httpEtag, "accept-ranges": "bytes" },
+          }), env, pdfCacheClass);
+        }
+        obj = full as R2ObjectBody;
+        pdfHeaders.etag = obj.httpEtag;
       }
 
+      // A satisfied Range request. R2 echoes the actually-served byte range on `obj.range` —
+      // but it does so for FULL gets too: against a real R2 binding under workerd, a get()
+      // whose forwarded Headers carry NO Range header still comes back with
+      // `range = {offset: 0, length: obj.size}`. Keying the 206 off `obj.range` alone therefore
+      // turned every plain GET of the 1.3 PDF into a 206 — which is exactly what the nightly
+      // canary sweep observed (`/en/1.3/vyos-documentation.pdf: status=206`) — and RFC 9110
+      // §15.3.7 only permits a 206 in answer to a request that actually carried a Range header.
+      // So: gate on the REQUEST first, then normalize whatever shape R2 handed back — and
+      // then CHECK that the two agree before promising a 206, because "R2 sliced it" and
+      // "R2 handed back everything" are the same shape on the wire.
+      //
+      // What R2 actually handed back, as concrete bounds. `obj.range` is absent only if a
+      // binding declines to report one, in which case the body is the complete object.
+      const actual = obj.range
+        ? resolveRange(obj.range, obj.size)
+        : { start: 0, length: obj.size };
+      const servedWhole = actual.start === 0 && actual.length === obj.size;
+
+      if (rangeApplies && rangeHeader !== null) {
+        const intent = classifyRangeHeader(rangeHeader, obj.size);
+        if (intent.kind === "unsatisfiable") {
+          // §14.2: "the server SHOULD send a 416"; §15.5.17: a 416 to a byte-range request
+          // SHOULD carry `Content-Range: bytes */<complete-length>`. Deliberately no
+          // content-type — there is no PDF payload on this response. 416 is >= 400 so
+          // apexHeaders() forces no-store, which is right: the verdict depends on the
+          // request's Range header and the cache key does not include it.
+          // R2 answers an unsatisfiable Range with the COMPLETE object, so the body being
+          // dropped here is the whole 29.2 MiB one — the largest abandoned stream on any
+          // path through this handler.
+          await discardBody(obj.body);
+          return apexHeaders(
+            new Response(null, {
+              status: 416,
+              headers: { etag: pdfHeaders.etag, "accept-ranges": "bytes",
+                         "content-range": `bytes */${obj.size}` },
+            }),
+            env,
+            pdfCacheClass,
+          );
+        }
+        // A 206 is owed only when the bytes R2 selected are the bytes the client asked for.
+        // `length === 0` means a zero-length representation (the only way R2 yields it) —
+        // e.g. a non-zero suffix-range, which §14.1.2 calls satisfiable, against an empty
+        // object. No valid Content-Range exists for an empty selection (§14.4 forbids a
+        // last-pos below the first-pos), so a 206 is unrepresentable. Fall through to the
+        // 200: §15.5.17's own note records that servers are free to ignore Range and answer
+        // with the complete representation, which for an empty object is exactly this body.
+        if (intent.kind === "single" && intent.length > 0 &&
+            actual.start === intent.start && actual.length === intent.length) {
+          pdfHeaders["content-range"] =
+            `bytes ${intent.start}-${intent.start + intent.length - 1}/${obj.size}`;
+          pdfHeaders["content-length"] = String(intent.length);
+          return apexHeaders(new Response(obj.body, { status: 206, headers: pdfHeaders }), env, pdfCacheClass);
+        }
+        // Otherwise no 206 is owed: either the spec was one §14.1.2 says to ignore
+        // (multi-range / malformed / unknown unit), or R2 declined a spec that this parser
+        // accepted — the grammar divergence classifyRangeHeader documents. Both leave R2
+        // having returned the complete object, so fall through to the 200 below.
+      }
+
+      // Serve what R2 actually handed back, described truthfully. `servedWhole` is the
+      // normal case and the only one a 200 can describe; a partial body under a 200 would
+      // ship a Content-Length that contradicts it. A partial body reaching HERE — past the
+      // agreement check above — means R2 sliced to bounds the request did not ask for, and
+      // there is no honest success response left: a 200 would misstate the length, and a
+      // 206 would answer with a range the client never requested, which §14.4 does not
+      // permit (Content-Range on a 206 describes the selected range, and no range was
+      // selected). This used to ship that illegal 206.
+      //
+      // So: drop the slice and fail. Re-reading the object for a clean 200 is the other
+      // option Codex offered, but it means a second conditional read with its own
+      // object-rewritten-between-reads handling — a copy of the If-Range block above, or a
+      // refactor of that live and currently-correct path — bought for a branch that cannot
+      // execute under today's workerd (round 3 established empirically that the Headers
+      // form ignores multi-range and returns the whole object). The log line is the part
+      // that earns its keep: it is the alarm that R2's range semantics have moved, and it
+      // is what would justify writing that re-read for real.
+      if (!servedWhole) {
+        console.log(JSON.stringify({
+          event: "r2-range-divergence", path: url.pathname, size: obj.size,
+          served: `${actual.start}+${actual.length}`, requested: rangeHeader ?? null,
+        }));
+        await discardBody(obj.body);
+        return themed(env, 503);
+      }
       pdfHeaders["content-length"] = String(obj.size);
       return apexHeaders(new Response(obj.body, { status: 200, headers: pdfHeaders }), env, pdfCacheClass);
     }