cursedbelt-server 4.9.0 → 4.11.1

package/src/nodeBuiltinsAreProbedByCalling.spec.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from 'bun:test';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * 🔴 **No `typeof x === 'function'` gate in front of a Node built-in. Probe by CALLING.**
+ *
+ * Measured 2026-09-19, the first real deploy of a cursedbelt app onto Workers:
+ * `https://collections.curtwphillips.workers.dev/healthz` answered `500` on **every path**,
+ * with 843 green tests behind it. One line did it — `bench/cpuClock.ts`:
+ *
+ * ```ts
+ * const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+ * ```
+ *
+ * Under `nodejs_compat`, workerd's strategy for the parts of `node:process` it does not
+ * implement is to PROVIDE the method and throw when it is called:
+ *
+ * ```
+ * Error [ERR_METHOD_NOT_IMPLEMENTED]: The process.cpuUsage method is not implemented
+ *     at process.cpuUsage (node-internal:public_process:235:11)
+ *     at Object.start (index.js:2772:30)     <- cpuBudget's middleware
+ * ```
+ *
+ * So the availability probe answered *yes* about the one runtime it exists to answer *no*
+ * about, and because `cpuBudget()` is mounted first by design, the throw landed in front of
+ * the whole app.
+ *
+ * 🔴 **That is a capability CLASS, not one method.** `nodejs_compat` stubs a great deal of
+ * `node:process`, `node:os` and `node:v8` the same way, and five apps have a "move to a
+ * Worker" task queued behind this library. `cpuClock.ts` is fixed; this is what stops the
+ * shape coming back somewhere else, where the next deploy would find it instead of a test.
+ *
+ * ## What it measures
+ *
+ * For every non-spec source file: blank the comments and string/template literals, work out
+ * which identifiers name a Node built-in (the `process` global, plus every binding imported
+ * from a `node:*` module, static or dynamic), and red on `typeof <that>.… === 'function'` in
+ * either direction and either operand order.
+ *
+ * `typeof x === 'undefined'` is deliberately NOT flagged: "is there a `process` at all" is a
+ * question a stub cannot lie about, and it is the guard that stops a bare reference throwing
+ * a `ReferenceError` before any `try` can catch it. What is forbidden is concluding a method
+ * WORKS because it EXISTS.
+ *
+ * ## The excuse, and why there is one
+ *
+ * A line carrying `probe-by-calling:ignore` (on it, or on the line above) is allowed — for
+ * the one honest use left: labelling. `cpuClock.ts` decides by calling and then uses a
+ * presence check only to say `(absent)` or `(throws)` in the clock's source string. Excuse
+ * the LINE, never delete the rule.
+ *
+ * ## Verified failing before it was trusted, 2026-09-19
+ *
+ * Four probes, each written to a scratch `src/server/bench/probe.agent.ts`, run, and deleted:
+ *
+ *   · the pre-fix line itself, `typeof process !== 'undefined' && typeof process.cpuUsage
+ *     === 'function'` → **red**, `1 pass, 1 fail`, naming
+ *     `server/bench/probe.agent.ts:1 — typeof process.cpuUsage === 'function'`
+ *   · the same line under a `probe-by-calling:ignore` comment → green — the excuse working
+ *   · `typeof process !== 'undefined'` alone → green — the carve-out working
+ *   · `import { homedir } from 'node:os'` + `typeof homedir === 'function'` → **red**, naming
+ *     line 2. That is the import-tracking half, which the `process` global never exercises.
+ *
+ * 🔴 The first probe is why there was a rewrite rather than a lucky green: run against the
+ * scanner's first draft it PASSED, because that draft blanked string literals along with
+ * comments and the pattern it hunts for ends in the literal `'function'`. A check whose
+ * first probe is green is a check nobody has seen work — see {@link stripComments}.
+ */
+
+const SRC = fileURLToPath(new URL('.', import.meta.url));
+
+/** `typeof A.b.c === 'function'`, and the three other ways to write it. */
+const TYPEOF_FUNCTION =
+  /typeof\s+([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)\s*[!=]==?\s*['"]function['"]|['"]function['"]\s*[!=]==?\s*typeof\s+([A-Za-z_$][\w$]*(?:\s*\.\s*[A-Za-z_$][\w$]*)*)/g;
+
+/** The one global that is a Node built-in without being imported. */
+const GLOBAL_NODE_BUILTINS = new Set(['process']);
+
+const IGNORE_MARKER = 'probe-by-calling:ignore';
+
+/**
+ * Blank COMMENTS, preserving line structure and every string literal, so a scanner is not
+ * fooled by prose.
+ *
+ * 🔴 Both halves of that are load-bearing, and each was found by a probe rather than by
+ * reasoning. Comments must go: this package is comment-dense and `cpuClock.ts`'s own header
+ * QUOTES the forbidden line as the bug it fixed, so a comment-blind scan reds on the fix.
+ * Strings must STAY: the pattern this looks for ends in `'function'`, which IS a string
+ * literal — blanking literals made the check silently unable to match anything at all, and
+ * a probe file carrying the exact pre-fix line passed. Strings are still TRACKED (never
+ * blanked) so that a `//` inside one — `'https://…'` — cannot be read as a comment.
+ */
+function stripComments(source: string): string {
+  let out = '';
+  let i = 0;
+  while (i < source.length) {
+    const c = source[i];
+    const next = source[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < source.length && source[i] !== '\n') {
+        out += ' ';
+        i += 1;
+      }
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) {
+        out += source[i] === '\n' ? '\n' : ' ';
+        i += 1;
+      }
+      out += '  ';
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      out += c;
+      i += 1;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === '\\') {
+          out += source[i];
+          i += 1;
+          if (i < source.length) {
+            out += source[i];
+            i += 1;
+          }
+          continue;
+        }
+        out += source[i];
+        i += 1;
+      }
+      out += source[i] ?? '';
+      i += 1;
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/** Every local name in this file that refers to something out of a `node:*` module. */
+function nodeBuiltinRoots(code: string): Set<string> {
+  const roots = new Set(GLOBAL_NODE_BUILTINS);
+  // `import x, { a, b as c } from 'node:os'` / `import * as os from 'node:os'`
+  // and `const { homedir } = await import('node:os')`.
+  const statics = /import\s+([\s\S]*?)\s+from\s+['"]node:[^'"]+['"]/g;
+  const dynamics =
+    /(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*await\s+import\s*\(\s*['"]node:/g;
+  // 🔴 Read from the RAW source, not the stripped copy: the module specifier is a string
+  // literal, so stripping blanks the very `'node:os'` this has to match. A binding named
+  // only inside a comment widens the rule by one identifier, which is the safe direction.
+  for (const m of code.matchAll(statics)) collectBindings(m[1] ?? '', roots);
+  for (const m of code.matchAll(dynamics)) collectBindings(m[1] ?? '', roots);
+  return roots;
+}
+
+/** Pull the local names out of an import clause: `x, { a, b as c }`, `* as ns`, `{ a }`. */
+function collectBindings(clause: string, into: Set<string>): void {
+  for (const part of clause.replace(/[{}]/g, ',').split(',')) {
+    const token = part.trim();
+    if (!token || token === 'type') continue;
+    const aliased = token.match(/\bas\s+([A-Za-z_$][\w$]*)$/);
+    const name = aliased ? aliased[1] : token.replace(/^type\s+/, '');
+    if (/^[A-Za-z_$][\w$]*$/.test(name)) into.add(name);
+  }
+}
+
+function sourceFiles(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    const full = `${dir}${entry}`;
+    if (statSync(full).isDirectory()) {
+      sourceFiles(`${full}/`, found);
+      continue;
+    }
+    // Specs are excluded: a test may legitimately assert about a probe, and a `typeof`
+    // gate in one cannot 500 a deployed app.
+    if (entry.endsWith('.ts') && !entry.endsWith('.spec.ts')) found.push(full);
+  }
+  return found;
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  text: string;
+}
+
+function scan(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of sourceFiles(SRC)) {
+    const raw = readFileSync(file, 'utf8');
+    const rawLines = raw.split('\n');
+    const code = stripComments(raw);
+    const roots = nodeBuiltinRoots(raw);
+    code.split('\n').forEach((line, index) => {
+      for (const m of line.matchAll(TYPEOF_FUNCTION)) {
+        const subject = (m[1] ?? m[2] ?? '').replace(/\s+/g, '');
+        const root = subject.split('.')[0];
+        if (!roots.has(root)) continue;
+        const here = rawLines[index] ?? '';
+        const above = rawLines[index - 1] ?? '';
+        if (here.includes(IGNORE_MARKER) || above.includes(IGNORE_MARKER)) continue;
+        violations.push({
+          file: file.slice(SRC.length),
+          line: index + 1,
+          text: `typeof ${subject} === 'function'`,
+        });
+      }
+    });
+  }
+  return violations;
+}
+
+describe('Node built-ins are probed by CALLING, never by typeof', () => {
+  it('has a real tree to scan — otherwise every assertion below passes vacuously', () => {
+    const files = sourceFiles(SRC);
+    expect(files.length).toBeGreaterThan(100);
+    // The scanner must actually resolve `node:*` imports, or the import half is dead.
+    const withOsImport = files.find((f) => f.endsWith('server/sqlite/export.ts'));
+    expect(withOsImport).toBeTruthy();
+    expect(nodeBuiltinRoots(readFileSync(withOsImport as string, 'utf8')).has('tmpdir')).toBe(true);
+  });
+
+  it('finds no typeof gate in front of a Node built-in anywhere in src', () => {
+    const violations = scan();
+    const message = violations.map((v) => `  ${v.file}:${v.line} — ${v.text}`).join('\n');
+    expect(
+      violations.length === 0 ? '' : `\n${message}\n\nProbe by calling, inside a try.\n`,
+    ).toBe('');
+  });
+});

package/src/publicSurface.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'bun:test';
+import { run } from '../scripts/publicSurface';
+
+/**
+ * The public-surface ratchet, wired into `bun run verify` at its cheapest correct
+ * home: `verify` ends in `bun test src`, so this needs no new script and cannot be a
+ * script somebody forgot to chain.
+ *
+ * WHY it exists, WHAT a symbol count includes and excludes, why the dependency list
+ * and the used-vs-exported ratio are deliberately NOT computed here, and what
+ * `--prune` may and may not do are all in the header of `scripts/publicSurface.ts` —
+ * one check, one baseline (`publicSurface.baseline`), one place that explains itself.
+ * This file is only the wiring.
+ *
+ * 🔴 Verified failing, 2026-09-19, before it was trusted — every branch, not just the
+ * easy one. Each probe was applied, observed, and removed again:
+ *
+ *   · `export const ratchetProbe = 1` appended to `src/server/errors.ts`
+ *       → this file's "ceiling" test red — `3 pass, 1 fail`, "exports no more symbols per
+ *         subpath than the baseline allows" — and the CLI:
+ *         "1 subpath(s) that gained exported symbols · ./errors — baseline allows 14,
+ *          exports 15 now"
+ *   · the same line appended to `src/server/guard/revocationStore.ts`, which is where the
+ *     transitive `export *` walk is actually visible: `./guard/revocations` points at that
+ *     file and `./guard`'s barrel does `export * from './revocationStore'`
+ *       → "2 subpath(s) that gained exported symbols · ./guard — baseline allows 25,
+ *          exports 26 now · ./guard/revocations — baseline allows 7, exports 8 now".
+ *         🔴 TWO from one line, which is the walk the header promises, seen working. Note
+ *         which probe does NOT do this: `.` is a barrel of 219 NAMED re-exports, so a new
+ *         symbol in `errors.ts` does not reach it. A probe chosen in the wrong module
+ *         would have "proved" the transitive walk by never exercising it.
+ *   · a `"./probe"` subpath added to `package.json` `exports`, pointed at
+ *     `./src/server/errors.ts`
+ *       → "1 export subpath(s) the baseline does not know · ./probe — NEW subpath,
+ *          14 exported symbol(s)"
+ *   · `VALIDATION_STATUS` removed from the re-export list in `src/server/errors.ts`, no prune
+ *       → "1 baseline entr(y|ies) that no longer match `exports` · ./errors — baseline
+ *          says 14, exports 13"
+ *   · a `5  ./gone` line added to the baseline by hand
+ *       → same failure, "./gone — baseline says 5, the subpath is gone". An entry
+ *         matching nothing is the half that stops a deleted module leaving an allowance.
+ *   · `--prune` run against the grown surface
+ *       → "refuses while the surface has GROWN — it may only lower the baseline", exit 1
+ *   · `--prune` run against the shrunk surface
+ *       → "pruned to 34 subpath(s), 0 removed, 990 symbols", exit 0, and `14  ./errors`
+ *         became `13  ./errors` in the file — the burn-down path
+ *   · `--seed` run over the seeded baseline
+ *       → "refuses: … already records 34 subpath(s)", exit 1
+ *
+ * Every probe was reverted with `git checkout -- <path>`; the tree afterwards held only
+ * this file, `scripts/publicSurface.ts` and `publicSurface.baseline`.
+ *
+ * A ratchet nobody has seen red is a ratchet nobody knows is wired up.
+ */
+const result = await run();
+
+describe('public surface', () => {
+	it('has measured a real surface', () => {
+		// Guards the three assertions below: if `exports` were ever read as empty, every
+		// one of them passes vacuously and the ratchet quietly dies.
+		// 🔴 20, not 34: a vacuity guard set at the real surface fails for the one reason
+		// a vacuity guard must never fail — the surface being healthy and simply smaller.
+		expect(result.surface.counts.size).toBeGreaterThan(20);
+	});
+
+	it('publishes no export subpath the baseline does not know', () => {
+		expect(
+			result.fresh,
+			`new public subpath(s) — a permanent promise. Add the line to publicSurface.baseline and say why:\n  ${result.fresh.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('exports no more symbols per subpath than the baseline allows', () => {
+		expect(
+			result.grown,
+			`a baseline entry is a ceiling, not an amnesty:\n  ${result.grown.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('has no baseline entry that outlived the surface it recorded', () => {
+		// The half that makes it a RATCHET: a deleted module may not leave an allowance
+		// behind for the next one to grow into.
+		expect(
+			result.stale,
+			`surface came off and the ratchet was not tightened — run \`bun scripts/publicSurface.ts --prune\`:\n  ${result.stale.join('\n  ')}`,
+		).toEqual([]);
+	});
+});

package/src/server/analytics/injectedScripts.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { foreignScriptSources, scriptsRefusedByCsp } from "./injectedScripts";
+import { MASTER_LOCK_CSP } from "../master-lock/guard";
 import { WEB_ANALYTICS_BEACON_ORIGIN, WEB_ANALYTICS_TAG } from "./webAnalytics";
 
 const PAGE = "https://collections.cursedalchemy.com/";
@@ -61,14 +62,17 @@ describe("scriptsRefusedByCsp", () => {
 	/**
 	 * 🔴 The failure path this whole file exists for — the owner's console line, turned into a
 	 * refusal. `script-src 'self'` with something injecting is exactly what he pasted.
+	 *
+	 * 🔴 **`MASTER_LOCK_CSP` itself, never a hand-typed copy of it.** `guard.ts:91` exports the
+	 * policy for exactly this reason and says so — *"EXPORTED so that nothing has to copy it"* —
+	 * and until 2026-09-21 the two readers that mattered both re-typed the string anyway: this
+	 * spec, and a byte-identical fork of this whole file in `apps/collections`. A policy that is
+	 * typed twice can be loosened in one place and stay green in the other, which would leave
+	 * this test passing about a CSP the wall no longer serves. Importing it means relaxing the
+	 * real policy REDS here, which is the only version of this test worth having.
 	 */
-	test("script-src 'self' refuses the injected beacon and names its origin", () => {
-		const refused = scriptsRefusedByCsp(
-			"default-src 'none'; style-src 'self'; script-src 'self'; connect-src 'self'; " +
-				"img-src data:; form-action 'none'; base-uri 'none'; frame-ancestors 'none'",
-			beacon,
-			PAGE,
-		);
+	test("the wall's own CSP refuses the injected beacon and names its origin", () => {
+		const refused = scriptsRefusedByCsp(MASTER_LOCK_CSP, beacon, PAGE);
 		expect(refused.map((s) => s.origin)).toEqual([WEB_ANALYTICS_BEACON_ORIGIN]);
 	});
 

package/src/server/analytics/webAnalytics.spec.ts

@@ -2,27 +2,46 @@ import { describe, expect, test } from "bun:test";
 import {
 	WEB_ANALYTICS_BEACON_ORIGIN,
 	WEB_ANALYTICS_BEACON_SRC,
+	WEB_ANALYTICS_BEACON_VERSION,
 	WEB_ANALYTICS_SITE_TAG,
 	WEB_ANALYTICS_SITE_TOKEN,
 	WEB_ANALYTICS_TAG,
+	beaconConfigsCarryVersion,
 	htmlCarriesWebAnalytics,
+	webAnalyticsBeaconConfig,
 	webAnalyticsBootstrap,
 	webAnalyticsTag,
 } from "./webAnalytics";
 
 /**
  * 🔴 The snippet, as Cloudflare's own `GET /accounts/<acct>/rum/site_info/list` returned it on
- * 2026-09-18 for `cursedalchemy.com`, unescaped. Pinning it byte-for-byte is the point: this
- * is the thing a shell pastes, and the day it drifts from the vendor's text is a day nobody
- * would otherwise notice until a dashboard stopped filling.
+ * 2026-09-18 for `cursedalchemy.com`, unescaped — and it records NOTHING. Measured 2026-09-22:
+ * the RUM endpoint 404s every payload this config produces, and four days of every manual
+ * shell's pageviews went with it while this test pinned the vendor's text as the safe choice.
  */
 const FROM_CLOUDFLARE =
 	`<!-- Cloudflare Web Analytics --><script type='module' src='https://static.cloudflareinsights.com/beacon.min.js' ` +
 	`data-cf-beacon='{"token": "bd88d63678b64bc89f9702f48846bc88"}'></script><!-- End Cloudflare Web Analytics -->`;
 
+/** The vendor's snippet with the one key it leaves out, which is what the fleet ships. */
+const WHAT_RECORDS = FROM_CLOUDFLARE.replace(`'{"token": `, `'{"version": "2024.11.0", "token": `);
+
 describe("the fleet's beacon", () => {
-	test("is exactly the snippet Cloudflare hands out for this site", () => {
-		expect(WEB_ANALYTICS_TAG).toBe(FROM_CLOUDFLARE);
+	test("is Cloudflare's snippet plus the `version` the endpoint requires", () => {
+		expect(WHAT_RECORDS).not.toBe(FROM_CLOUDFLARE);
+		expect(WEB_ANALYTICS_TAG).toBe(WHAT_RECORDS);
+		expect(webAnalyticsBeaconConfig()).toBe(`{"version": "${WEB_ANALYTICS_BEACON_VERSION}", "token": "${WEB_ANALYTICS_SITE_TOKEN}"}`);
+	});
+
+	test("🔴 a config without `version` is refused — the vendor's own text among them", () => {
+		expect(htmlCarriesWebAnalytics(FROM_CLOUDFLARE)).toBe(false);
+		expect(beaconConfigsCarryVersion(FROM_CLOUDFLARE)).toBe(false);
+		// Two beacons on one page, one of them without it, is still a page that records nothing.
+		expect(beaconConfigsCarryVersion(WHAT_RECORDS + FROM_CLOUDFLARE)).toBe(false);
+		// The edge's own spelling — no spaces, other keys after — is accepted.
+		expect(beaconConfigsCarryVersion(`data-cf-beacon='{"version":"2024.11.0","token":"x","r":1,"spa":2}'`)).toBe(true);
+		// And a page with no config at all is not vacuously fine.
+		expect(beaconConfigsCarryVersion("<html></html>")).toBe(false);
 	});
 
 	test("carries the site TOKEN, never the site TAG", () => {
@@ -79,7 +98,7 @@ describe("the hostname guard", () => {
 		for (const host of ["cursedalchemy.com", "collections.cursedalchemy.com", "vault.cursedalchemy.com"]) {
 			const { appended, attrs } = runBootstrap(host);
 			expect(appended, `${host} should load the beacon`).toEqual([WEB_ANALYTICS_BEACON_SRC]);
-			expect(attrs["data-cf-beacon"]).toBe(`{"token": "${WEB_ANALYTICS_SITE_TOKEN}"}`);
+			expect(attrs["data-cf-beacon"]).toBe(webAnalyticsBeaconConfig());
 		}
 	});
 
@@ -113,7 +132,7 @@ describe("htmlCarriesWebAnalytics", () => {
 		// A formatter is allowed to break the attributes across lines; the check must survive it.
 		const rewrapped =
 			`<script\n\ttype="module"\n\tsrc="${WEB_ANALYTICS_BEACON_SRC}"\n` +
-			`\tdata-cf-beacon='{"token": "${WEB_ANALYTICS_SITE_TOKEN}"}'\n></script>`;
+			`\tdata-cf-beacon='${webAnalyticsBeaconConfig()}'\n></script>`;
 		expect(htmlCarriesWebAnalytics(rewrapped)).toBe(true);
 	});
 

package/src/server/analytics/webAnalytics.ts

@@ -53,7 +53,33 @@ export const WEB_ANALYTICS_SITE_TAG = "d1bea8562544421fbd2db5f11b74d1cc";
 export const WEB_ANALYTICS_SITE_TOKEN = "bd88d63678b64bc89f9702f48846bc88";
 
 /**
- * The snippet, exactly as Cloudflare's own `site_info` endpoint spells it.
+ * 🔴 The `version` the beacon's config must carry, or NOTHING is recorded.
+ *
+ * Measured 2026-09-22, after the RUM API showed every manual-snippet shell recording ZERO
+ * pageviews from 2026-09-19 on — collections, music, roms, flix, station and desk, which had
+ * been 130–290 a day between them — while the hosts still on the edge's injection kept
+ * recording. The beacon copies this value into its payload as `versions.fl`, and
+ * `cloudflareinsights.com/cdn-cgi/rum` answers a payload without `fl` with a **404 that carries
+ * no CORS header**, which a browser prints as a CORS refusal and nobody reads as "recorded
+ * nothing". Same token, same src, driven in a real browser from a `*.cursedalchemy.com` origin:
+ * `{"token": …}` → 404 every time; `{"version": "2024.11.0", "token": …}` → 204 every time,
+ * whether the script path was pinned or not. Any value was accepted; this one is what the
+ * edge's own injection carries, so it is the value Cloudflare is known to send.
+ *
+ * Cloudflare's own `site_info` snippet OMITS it, so "exactly the vendor's text" was the
+ * defect, not the safety it looked like. `tools/check-web-analytics.ts` reds a hand copy
+ * without it.
+ */
+export const WEB_ANALYTICS_BEACON_VERSION = "2024.11.0";
+
+/** The `data-cf-beacon` value — one spelling for the tag, the bootstrap and every hand copy. */
+export function webAnalyticsBeaconConfig(token: string = WEB_ANALYTICS_SITE_TOKEN): string {
+	return `{"version": "${WEB_ANALYTICS_BEACON_VERSION}", "token": "${token}"}`;
+}
+
+/**
+ * The snippet as Cloudflare's own `site_info` endpoint spells it — plus the `version` key it
+ * leaves out, without which nothing is recorded (see {@link WEB_ANALYTICS_BEACON_VERSION}).
  *
  * 🔴 The single-quoted attributes and the space after `"token":` are Cloudflare's, not a
  * style choice, and they are kept because this string is COMPARED against what an app's
@@ -68,7 +94,7 @@ export function webAnalyticsTag(token: string = WEB_ANALYTICS_SITE_TOKEN): strin
 	return (
 		"<!-- Cloudflare Web Analytics -->" +
 		`<script type='module' src='${WEB_ANALYTICS_BEACON_SRC}' ` +
-		`data-cf-beacon='{"token": "${token}"}'></script>` +
+		`data-cf-beacon='${webAnalyticsBeaconConfig(token)}'></script>` +
 		"<!-- End Cloudflare Web Analytics -->"
 	);
 }
@@ -121,7 +147,7 @@ export function webAnalyticsBootstrap(token: string = WEB_ANALYTICS_SITE_TOKEN):
 		`\t\tvar beacon = document.createElement("script");`,
 		`\t\tbeacon.type = "module";`,
 		`\t\tbeacon.src = "${WEB_ANALYTICS_BEACON_SRC}";`,
-		`\t\tbeacon.setAttribute("data-cf-beacon", '{"token": "${token}"}');`,
+		`\t\tbeacon.setAttribute("data-cf-beacon", '${webAnalyticsBeaconConfig(token)}');`,
 		`\t\tdocument.head.appendChild(beacon);`,
 		"\t}",
 		"</script>",
@@ -133,12 +159,23 @@ export function webAnalyticsBootstrap(token: string = WEB_ANALYTICS_SITE_TOKEN):
  *
  * Deliberately NOT a substring test against {@link WEB_ANALYTICS_TAG}: a shell is authored by
  * hand and a formatter is allowed to re-wrap the tag across lines or re-order its attributes.
- * What must be true is that the beacon's source is there AND that it is carrying the right
- * token — the two halves that decide whether a pageview is recorded at all.
+ * What must be true is that the beacon's source is there, that it is carrying the right
+ * token, and that its config carries a `version` — the three things that decide whether a
+ * pageview is recorded at all. The third was missed until 2026-09-22 and cost four days of
+ * every manual shell's data; see {@link WEB_ANALYTICS_BEACON_VERSION}.
  */
 export function htmlCarriesWebAnalytics(
 	html: string,
 	token: string = WEB_ANALYTICS_SITE_TOKEN,
 ): boolean {
-	return html.includes(WEB_ANALYTICS_BEACON_SRC) && html.includes(token);
+	return html.includes(WEB_ANALYTICS_BEACON_SRC) && html.includes(token) && beaconConfigsCarryVersion(html);
+}
+
+/**
+ * Every `data-cf-beacon` config in `html` names a `version` — and there is at least one.
+ * Read up to the config's closing brace, so key order and a formatter's spacing do not matter.
+ */
+export function beaconConfigsCarryVersion(html: string): boolean {
+	const configs = [...html.matchAll(/data-cf-beacon[^{]{0,24}(\{[^}]*\})/g)].map((m) => m[1] ?? "");
+	return configs.length > 0 && configs.every((c) => /"version"\s*:\s*"[^"]+"/.test(c));
 }