cursedops 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # cursedops
 
-Three build-and-ops answers that two apps independently wrote the same way.
+Build-and-ops answers that the apps here wrote independently and identically.
 
 ```sh
 bun add cursedops
@@ -10,7 +10,8 @@ bun add cursedops
 |---|---|
 | `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path |
 | `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent |
-| `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code |
+| `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code — and the one check no app owns: every address of a deployment serving the same built client |
+| `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers — and the API floor: the predicates, the trailing-slash normaliser and the default 404 body that keep an unmatched `/api/...` from ever being answered with the app shell |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
 name, a hostname, a port or a route.
@@ -41,6 +42,15 @@ So the entry rule here is arithmetic, not judgement:
 A fourth rule follows from the first three: **an addition that only one app will use
 does not go in.** That is a library that exists to be refactored later.
 
+🔴 **`sameDeployedShell` is the one entry that rule 1 did not let in, and it is recorded
+here rather than quietly excepted.** It was written once, by `patterns`, not twice —
+what admits it is rule 3 at a size rule 1 cannot measure: the fault it catches was
+invisible for six days on the app that had it, and the other five apps behind or moving
+behind an edge Worker still cannot tell a working deploy from a working cache. A check
+told ONE NAME is a check about that name; this one is about a property every deployment
+with two addresses has. It buys the exception by being pinned to a failure it has
+actually caught — `src/smoke.test.ts` runs it against the genuine 2026-09-12 shell.
+
 ### What was deliberately left in the apps
 
 The comparison that produced this library found three areas that are genuinely
@@ -110,10 +120,84 @@ await guarded(smoke, "gate", async () => {
 smoke.finish();   // exits 0, 1 or 2
 ```
 
-No checks, ever. The checks are the part `desk` and `flix` wrote differently on purpose,
+One check, and it is about the ADDRESSES of a deployment rather than about any app:
+
+```ts
+import { sameDeployedShell } from "cursedops/smoke";
+
+// every address of one deployment, not "edge vs origin" — an app may have no
+// origin left. A Worker's second address is its uncached *.workers.dev preview.
+await sameDeployedShell(smoke, [smoke.base, `http://127.0.0.1:${port}`]);
+```
+
+🔴 It refuses when the addresses name different built assets, and it records that as an
+**edge fault (exit 2), never a rollback** — the origin is serving what this checkout
+built, and reverting it cannot reach the Worker, cache rule or Assets binding in front.
+Measured 2026-09-18 on `patterns`: the edge served a shell built 2026-09-12 out of a
+Worker nobody knew about, and every automated surface stayed green for **six days**.
+Only same-origin `.js`/`.css` references are compared, because the zone injects a Web
+Analytics beacon in front of the edge and not on loopback — a check that reds on a
+healthy deploy is one somebody turns off.
+
+Nothing else. The checks are the part `desk` and `flix` wrote differently on purpose,
 and a shared kit that starts absorbing route lists and health-payload shapes is how the
 last one reached 277 files.
 
+## `cursedops/serve`
+
+```ts
+import { contentTypeFor, fileWithin, installCrashHandlers, isHashedAsset } from "cursedops/serve";
+
+installCrashHandlers("myapp");                        // one log line, then exit 1
+const file = fileWithin(clientDir, url.pathname);     // null unless it is really inside
+if (!file) return c.notFound();
+return new Response(Bun.file(file), {
+  headers: {
+    "content-type": contentTypeFor(file),
+    "cache-control": isHashedAsset(url.pathname) ? ONE_YEAR : "no-cache",
+  },
+});
+```
+
+🔴 `fileWithin` is the reason this subpath exists rather than the convenience of the
+other three. It is the check that stops `%2e%2e%2f` reaching the filesystem, and on
+2026-09-17 there were **eight** of it — one per app, character-identical, with nothing in
+the generation counting them. Eight copies of a security guarantee are eight guarantees:
+a fix in one is a fix in one.
+
+### The verdict for every symbol in the `serve.ts` family
+
+Measured 2026-09-17 across `collections`, `family`, `flix`, `music`, `patterns`, `roms`,
+`station` and `vault` — the eight apps that have a `src/server/serve.ts`. The files are
+247–387 lines and all eight differ, which is why no `diff` ever flagged them; the bodies
+below were compared with whitespace and comments normalised away.
+
+| symbol | identical in | verdict |
+|---|---:|---|
+| `fileWithin` | 8 of 8 | **moved.** The traversal guard. Entry rule 3 — a trap somebody paid for — in its purest form |
+| `installCrashHandlers` | 8 of 8 | **moved.** The app's name is a parameter; it is the only app-shaped thing the four touch |
+| `contentTypeFor` | 8 of 8 | **moved.** Extension → MIME, plus its private `CONTENT_TYPES` table, which was also 8 of 8 |
+| `isHashedAsset` | 8 of 8 | **moved.** Vite's own output convention, which is the bundler's identity and not the app's |
+| `clientDirOf` | 6 of 6 that have it | **stays.** One line, and six apps pin it with their own `clientDir.test.ts` against their own `vite.config.ts`. WHERE an app's build writes is app identity — entry rule 2 — and it is the line that once served `public/` and took a live app down |
+| `createServer` / `createApp` | 0 — all eight differ | **stays.** Route tables, health payloads, gates and body limits. This is the 277-file mistake's front door |
+| `parseRange` / `fileResponse` | `flix` and `station` only | **stays for now.** Two apps, so rule 1 is satisfiable, but rule 3 is not: nothing has been paid for yet, and a `Range` implementation shared by two apps that stream different things is a guess. The trigger to revisit is a THIRD app that needs byte ranges |
+| `API_PREFIX`, `isApiPath`, `canonicalApiPath`, `canonicalApiRequest`, `apiNotFoundBody` | `station` only | **stays.** One app, and rule 4 says an addition one app will use does not go in. `apiNotFoundBody` also writes a sentence the owner reads on a page — identity, not mechanism |
+
+🔴 **The task that ordered this move recorded `contentTypeFor` and `isHashedAsset` as
+7 of 8, with `station` differing. They did not differ.** All four bodies were identical
+in all eight apps when the move was made, so nothing had to converge and no app's
+behaviour changed on adoption. The count came from a census of the whole `serve.ts`
+family rather than of these two bodies; `bun tools/check-copies.ts` in the generation
+repo is the live answer either way.
+
+One behaviour is NOT a byte-for-byte carry, and `src/serve.ts`'s header argues it in
+full: the eight copies checked containment lexically and were therefore blind to a
+symlink under the root pointing out of it. `fileWithin` here resolves the real path of
+**both** sides after the lexical check, which refuses the escape while leaving every
+input the eight copies refused refused, at the same cost. A symlinked ancestor of the
+root cancels out — which is the failure a one-sided `realpath` would have shipped to
+every app on this machine, and is its own test.
+
 ## Verifying
 
 ```sh

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "cursedops",
-	"version": "0.1.0",
-	"description": "The three build-and-ops answers two apps independently wrote the same way: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, and the scaffolding of a deployed smoke. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
+	"version": "0.2.1",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard and the API floor among them. Mechanism only — no app knows its name from here. Bun, zero dependencies, ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome check .",
 		"test": "bun test src",
-		"paths": "bun ../../tools/check-paths.ts .",
+		"paths": "bun run scripts/paths.ts",
 		"verify": "bun run paths && bun run typecheck && bun run lint && bun run test",
 		"prepublishOnly": "bun run verify"
 	},
@@ -24,6 +24,12 @@
 			"source": "./src/launchd.ts",
 			"import": "./src/launchd.ts"
 		},
+		"./serve": {
+			"types": "./src/serve.ts",
+			"bun": "./src/serve.ts",
+			"source": "./src/serve.ts",
+			"import": "./src/serve.ts"
+		},
 		"./smoke": {
 			"types": "./src/smoke.ts",
 			"bun": "./src/smoke.ts",

package/src/serve.ts

@@ -0,0 +1,265 @@
+/**
+ * The helpers every app's `src/server/serve.ts` wrote the same way — the
+ * path-traversal guard among them, and the API floor.
+ *
+ * ## Why this is a library and not eight copies
+ *
+ * Measured 2026-09-17 by the apps maintenance sweep, and again by this move before
+ * it started: `collections`, `family`, `flix`, `music`, `patterns`, `roms`,
+ * `station` and `vault` each have a `src/server/serve.ts`. The FILES differ — 247
+ * to 387 lines, eight distinct versions, which is why no `diff` ever flagged them —
+ * but these four bodies are character-identical in **eight of eight**, with the
+ * whitespace and comments normalised away.
+ *
+ * 🔴 **`fileWithin` is why this was urgent rather than tidy.** It is the check that
+ * stops `%2e%2e%2f` reaching the filesystem. Eight copies of a security guarantee
+ * are eight guarantees: a fix in one is a fix in one, and the other seven apps keep
+ * the hole. That is the arithmetic the entry rule in `../README.md` asks for —
+ * rule 1 (two apps wrote it independently) answered eight times over, rule 2
+ * (mechanism, not identity — nothing here knows an app's name, port, hostname or
+ * routes; `installCrashHandlers` is HANDED the name), and rule 3 (a trap somebody
+ * paid for — a traversal guard is the definition of one).
+ *
+ * `clientDirOf` deliberately did NOT come with them. It is one line, six apps pin
+ * it with their own `clientDir.test.ts` against their own `vite.config.ts`, and
+ * where an app's build writes is app identity.
+ *
+ * `tools/check-copies.baseline` in the generation repo carried these four at
+ * `8  <symbol> src/server/serve.ts` and is the census that will notice if a copy
+ * comes back.
+ *
+ * ## 🔴 The one behaviour that is NOT a byte-for-byte carry
+ *
+ * The eight copies resolved containment LEXICALLY — `resolve(join(root, …))` and a
+ * `startsWith` — which is correct for `..` and for `%2e%2e%2f`, and blind to a
+ * symlink inside the root that points out of it. {@link fileWithin} now resolves
+ * the real path of both sides before comparing, so a symlink cannot walk out
+ * either. It is a strict tightening, not a change of contract:
+ *
+ *   - the lexical check runs FIRST and unchanged, so every input the eight copies
+ *     refused is still refused, at the same cost;
+ *   - a symlinked ANCESTOR of the root cancels out, because the root is resolved
+ *     the same way — the failure mode a naive `realpath` on one side only would
+ *     have introduced, and the reason this is not one line;
+ *   - every caller today passes a Vite `dist/`, and all eight were checked for
+ *     symlinks on 2026-09-17: there are none. So no app's behaviour moves, and the
+ *     day one of them serves a directory it did not build, the guard already holds.
+ *
+ * `serve.test.ts` drives both halves, including the symlink escape, because a guard
+ * that has only ever been seen passing is a guard nobody has proved can fail.
+ *
+ * ## 🔴 The API floor, added 2026-09-18 — and why it is here rather than in an app
+ *
+ * The second family in this file, and it arrives by the same arithmetic. `station` and
+ * `patterns` each wrote a floor — a rule that an unmatched `/api/...` is answered with a
+ * phrase and never with the single-page shell — independently, in different shapes, for
+ * the same incident. That is entry rule 1 twice over. Rule 2 holds because nothing below
+ * looks anything up: the app's name, its commit and the body it chooses to send all
+ * arrive as arguments, and there is no Hono type in this file, so the three lines of
+ * `app.all(...)` wiring stay in the app that owns the router. Rule 3 is the measurement:
+ *
+ *   > 2026-09-17. `station`'s Openclaw page had never loaded on any commit. The client
+ *   > asked for `/api/openclaw/`; Hono mounts that sub-app's `get("/")` at
+ *   > `/api/openclaw` — `mergePath("/api/openclaw", "/")` drops the trailing slash — and
+ *   > then matches strictly, so the request matched nothing, fell into `app.get("*")`,
+ *   > and came back as 1.7 KB of `index.html` with a **200**. The client's honest reading
+ *   > of an HTML body was *"that is what an API older than this page looks like — deploy
+ *   > this commit and reload"*, which sent the owner at a deploy that could not have
+ *   > helped.
+ *
+ * Both halves of that are here, because a floor without the normaliser fixes the symptom
+ * the owner did not have: {@link canonicalApiPath} makes the trailing slash a non-event,
+ * and {@link isApiPath} + {@link apiNotFoundBody} make every remaining miss a JSON 404
+ * that names the route, the app and the commit answering. A wrong path says "wrong path";
+ * a stale process says which commit it is.
+ *
+ * 🔴 **{@link apiNotFoundBody} is the DEFAULT body, not the only one.** `patterns` sends
+ * `{status, code, error}` through its own `reply.refuse` and deliberately says less —
+ * its floor faces the public internet, where the app's name and commit are one bit more
+ * than a scanner should get. An app that knows something this library cannot keeps its
+ * own body and takes the two predicates; that is the `cwip/asset-budget` shape, and it is
+ * what stops this growing into the kit it replaced.
+ */
+
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, normalize, resolve, sep } from "node:path";
+
+/**
+ * Extension → content type, for what a built single-page client actually contains.
+ *
+ * Not a full MIME database on purpose: an app serving a type that is not here is an
+ * app serving something its build did not produce, and `application/octet-stream`
+ * is the honest answer to that rather than a guess.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+	html: "text/html; charset=utf-8",
+	js: "text/javascript; charset=utf-8",
+	mjs: "text/javascript; charset=utf-8",
+	css: "text/css; charset=utf-8",
+	json: "application/json; charset=utf-8",
+	svg: "image/svg+xml",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	avif: "image/avif",
+	ico: "image/x-icon",
+	woff: "font/woff",
+	woff2: "font/woff2",
+	txt: "text/plain; charset=utf-8",
+	map: "application/json; charset=utf-8",
+};
+
+/** The `content-type` for a path, by extension — `application/octet-stream` if unknown. */
+export const contentTypeFor = (path: string): string =>
+	CONTENT_TYPES[path.slice(path.lastIndexOf(".") + 1).toLowerCase()] ?? "application/octet-stream";
+
+/**
+ * Vite's own output convention: `name-<8+ hex/base64url chars>.ext` under
+ * `/assets/`. Only these get the immutable year.
+ */
+export const isHashedAsset = (urlPath: string): boolean =>
+	/^\/assets\/[^/]+-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/.test(urlPath);
+
+/**
+ * The file `urlPath` names inside `root`, or `null`.
+ *
+ * 🔴 The containment check is the point. `decodeURIComponent` then `normalize`
+ * collapses `..`, and the result must still start with the root — otherwise
+ * `/assets/..%2f..%2f..%2fetc%2fpasswd` reads whatever the process can. A
+ * directory, a missing file and a malformed escape are all `null`; a caller that
+ * gets a string has a regular file it may open.
+ *
+ * The final `realpath` pass is the one thing the eight app copies did not do — see
+ * the module header for why it cannot break a caller.
+ */
+export function fileWithin(root: string, urlPath: string): string | null {
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(urlPath);
+	} catch {
+		return null; // a malformed escape is not a path
+	}
+	if (decoded.includes("\0")) return null;
+	const full = resolve(join(root, normalize(decoded)));
+	const base = resolve(root);
+	if (full !== base && !full.startsWith(base + sep)) return null;
+	if (!existsSync(full) || !statSync(full).isFile()) return null;
+	// Lexically inside, and the file is there. Now the same question of the DISK: a
+	// symlink under the root is the one way a path can pass the check above and
+	// still read something outside. Both sides, or a symlinked ancestor of the root
+	// would refuse every file it holds.
+	let realFull: string;
+	let realBase: string;
+	try {
+		realFull = realpathSync(full);
+		realBase = realpathSync(base);
+	} catch {
+		return null; // it existed a line ago; whatever it is now, do not serve it
+	}
+	if (realFull !== realBase && !realFull.startsWith(realBase + sep)) return null;
+	return full;
+}
+
+/**
+ * Say what killed the process, once, before it goes.
+ *
+ * The whole value is the log line. An app holding SQLite handles that Bun closes on
+ * exit and nothing else in flight has nothing to drain — what was missing in the
+ * previous generation was not cleanup, it was ever finding out why a long-running
+ * process had stopped.
+ *
+ * 🔴 `name` is a parameter rather than anything this library could look up. That is
+ * the whole of rule 2: the only app-shaped thing these four helpers touch arrives
+ * as an argument.
+ */
+/** The API namespace. See the module header: nothing under it may answer with the shell. */
+export const API_PREFIX = "/api";
+
+/**
+ * Is this path inside the API namespace? `/api` itself counts; `/apiary` does not.
+ *
+ * 🔴 The namespace ITSELF is the case every hand-rolled floor missed. A Hono
+ * `app.all("/api/*")` does not match a bare `/api` — the pattern requires the slash — so
+ * the one path most likely to be typed by hand fell through to the shell in the two apps
+ * that already believed they had a floor.
+ */
+export const isApiPath = (urlPath: string): boolean =>
+	urlPath === API_PREFIX || urlPath.startsWith(`${API_PREFIX}/`);
+
+/**
+ * The path an API request SHOULD have asked for, or `null` when it already did.
+ *
+ * 🔴 One rule, and it is the one that broke the Openclaw page: a trailing slash on an API
+ * path is never meaningful. Hono mounts a sub-app's `get("/")` at the mount point WITHOUT
+ * a trailing slash and then matches strictly, so `/api/openclaw/` is a different path
+ * from `/api/openclaw` and matched nothing at all. Normalising once, in front of the
+ * router, means no caller anywhere can spell it the losing way again — which a fix in the
+ * one client module that happened to do it would not have bought.
+ *
+ * The query string is untouched: only the path is rewritten.
+ */
+export function canonicalApiPath(urlPath: string): string | null {
+	if (!isApiPath(urlPath) || !urlPath.endsWith("/")) return null;
+	const trimmed = urlPath.replace(/\/+$/, "");
+	return trimmed === urlPath ? null : trimmed;
+}
+
+/**
+ * The same normalisation, applied to a whole request. Returns the request unchanged when
+ * there is nothing to normalise, so the hot path allocates nothing.
+ *
+ * 🔴 Wrap it around the ONE function every response leaves through — the `fetch` a host
+ * hands `Bun.serve` or exports from a Worker — and never as a Hono middleware. Hono runs
+ * middleware in registration order against handlers registered AFTER it, and an app's
+ * routes are mounted before the host is built; a middleware added at that point runs for
+ * none of them. It also cannot change which route matches, which is the entire job here.
+ */
+export function canonicalApiRequest(request: Request): Request {
+	const url = new URL(request.url);
+	const canonical = canonicalApiPath(url.pathname);
+	if (canonical === null) return request;
+	url.pathname = canonical;
+	return new Request(url, request);
+}
+
+/**
+ * What an unmatched API path answers — a JSON 404 that names itself.
+ *
+ * 🔴 The commit is in the body on purpose. The two reasons a route is missing are "this
+ * path never existed" and "this process is older than the page that asked", and they need
+ * different hands; without the commit a client can only guess, and the guess one printed
+ * for the owner sent him to deploy a commit that would not have fixed anything.
+ *
+ * 🔴 Safe to publish only where the floor sits BEHIND the app's gate, which is where every
+ * caller puts it — an unauthenticated request is answered 401 by the gate, matched or not.
+ * An app whose API namespace is open sends its own, terser body instead; see the module
+ * header.
+ */
+export function apiNotFoundBody(
+	method: string,
+	urlPath: string,
+	app: string,
+	commit: string | null | undefined,
+): { error: string; route: string; app: string; commit: string | null } {
+	return {
+		error:
+			`no such route: ${method} ${urlPath}. ${app} is serving ${commit ?? "an unreadable commit"} ` +
+			"and has no such API route — either the path is wrong, or this process is older than the page " +
+			"that asked for it. It is NOT the app shell: nothing under /api/ is ever answered with HTML.",
+		route: `${method} ${urlPath}`,
+		app,
+		commit: commit ?? null,
+	};
+}
+
+export function installCrashHandlers(name: string): void {
+	process.on("uncaughtException", (error) => {
+		console.error(`[${name}] uncaught exception — exiting`, error);
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		console.error(`[${name}] unhandled rejection — exiting`, reason);
+		process.exit(1);
+	});
+}

package/src/smoke.ts

@@ -39,6 +39,22 @@
  * exactly where it is. {@link Smoke.finish} is the single place that code is
  * decided, so the two apps reading it cannot disagree about what a `2` meant.
  *
+ * ## The ONE check that lives here, and why it is not an app's to write
+ *
+ * {@link sameDeployedShell} is the exception to "no checks", and the paragraph
+ * above is its argument rather than an argument against it: every incident in that
+ * list is *the deploy said yes and the visitor got something else*, and asking one
+ * address can never see that. It is a check about the ADDRESSES of a deployment,
+ * which every app has and no app owns — not about any app's routes, payloads or
+ * titles, which stay out.
+ *
+ * Measured 2026-09-18 on `patterns`: the origin served the shell this checkout
+ * built, `patterns.cursedalchemy.com` served one built on 2026-09-12 out of a
+ * Worker nobody knew about, and **every automated surface was green for six days.**
+ * The app-local implementation that found it — `apps/patterns/scripts/worker-smoke.ts`,
+ * `CROSS_CHECKS` — is what this generalises, because five more apps are moving
+ * behind an edge Worker and a check told ONE NAME is a check about that name.
+ *
  * ## What this module will never grow
  *
  * No route lists, no health-payload shapes, no upload sizes, no titles. Those are
@@ -224,3 +240,184 @@ export async function guarded(smoke: Smoke, check: string, body: () => Promise<v
 		smoke.record(check, false, `could not complete against ${smoke.base}: ${failed.message}${smoke.dnsHint(failed)}`);
 	}
 }
+
+/** What one address said when it was asked for the shell. */
+export interface AddressShell {
+	/** The address as it was passed in. */
+	address: string;
+	/** Same-origin built files the shell references, de-duplicated and sorted. */
+	assets: string[];
+}
+
+export interface ShellAgreement {
+	/** True only when every address named the same non-empty set of built files. */
+	agreed: boolean;
+	/** One line naming which address served what — the whole point on a failure. */
+	detail: string;
+	shells: AddressShell[];
+}
+
+export interface ShellOptions {
+	/** The document to compare. The shell, so `/` unless an app's entry is elsewhere. */
+	path?: string;
+	/** Per-request ceiling, matching {@link SmokeOptions.timeoutMs}'s default. */
+	timeoutMs?: number;
+	/** The cache-busting query value. Injected so a test can be deterministic. */
+	cacheBust?: () => string;
+	/** Injected for tests. Defaults to the global `fetch`. */
+	fetch?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+/**
+ * `src="…"` and `href="…"`, either quote. Attribute scan, not a parser — see
+ * {@link builtAssetsIn}. The leading whitespace is what keeps `data-src` and
+ * `xlink:href` out of the comparison.
+ */
+const REFERENCE = /\s(?:src|href)\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+/** What a bundler emits and a shell names. Extensions, because hashes are not universal. */
+const BUILT_FILE = /\.(?:js|mjs|cjs|css)$/i;
+
+function hostOf(address: string): string | null {
+	try {
+		return new URL(address).host;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The built files a shell references, as paths — the stable part of an HTML body.
+ *
+ * 🔴 **Same-origin only, and that is load-bearing rather than tidy.** The two
+ * addresses of one deployment legitimately differ in what a third party injected:
+ * on the app this check was built for, the zone's Web Analytics Automatic Setup
+ * appends `static.cloudflareinsights.com/beacon.min.js` at the edge and not on
+ * loopback. Comparing bodies, or comparing every `.js` a shell names, fails on that
+ * every time — a check that reds on a healthy deploy is one somebody turns off.
+ *
+ * Nothing here parses HTML: a bundler-emitted shell is machine-written, and the
+ * comparison only has to be STABLE between two copies of the same one.
+ */
+export function builtAssetsIn(html: string, address: string): string[] {
+	const host = hostOf(address);
+	const found = new Set<string>();
+	for (const match of html.matchAll(REFERENCE)) {
+		const raw = (match[1] ?? match[2] ?? "").trim();
+		if (!raw) continue;
+		let url: URL;
+		try {
+			url = new URL(raw, address);
+		} catch {
+			continue;
+		}
+		if (url.host !== host) continue;
+		if (!BUILT_FILE.test(url.pathname)) continue;
+		found.add(url.pathname);
+	}
+	return [...found].sort();
+}
+
+/**
+ * Ask every address of ONE deployment for the shell, and say whether they agree.
+ *
+ * 🔴 The assertion is **"every address agrees"**, not "the edge matches the
+ * origin" — which is the shape that survives an app having no origin left to
+ * compare against, and the reason this takes a list rather than a pair. Two is the
+ * usual list (the public hostname and `http://127.0.0.1:<port>`); a Worker's is the
+ * custom domain and its `*.workers.dev` preview, because a preview URL is not
+ * behind the cache.
+ *
+ * Every request is cache-busted, because the question is what that address HAS,
+ * not what it hands a repeat visitor.
+ */
+export async function compareDeployedShells(addresses: string[], options: ShellOptions = {}): Promise<ShellAgreement> {
+	const path = options.path ?? "/";
+	const timeoutMs = options.timeoutMs ?? 20_000;
+	const cacheBust = options.cacheBust ?? (() => Math.random().toString(36).slice(2));
+	const send = options.fetch ?? ((url: string, init: RequestInit) => fetch(url, init));
+
+	// 🔴 Loud, not silent. One address cannot disagree with itself, so a run that
+	// quietly passed here would be a skip wearing a pass — the exact reading that
+	// let a six-day-old shell sit behind six green surfaces.
+	if (addresses.length < 2) {
+		return {
+			agreed: false,
+			detail:
+				`needs at least two addresses of the same deployment and got ${addresses.length}` +
+				` (${addresses.join(", ") || "none"}) — one address cannot disagree with itself,` +
+				" so there is nothing here that could have failed.",
+			shells: [],
+		};
+	}
+
+	const shells: AddressShell[] = [];
+	const problems: string[] = [];
+	for (const address of addresses) {
+		const url = new URL(path, address);
+		url.searchParams.set("cb", cacheBust());
+		// 🔴 Re-thrown WITH the address and with the original message intact: which
+		// of the addresses could not be reached is the whole diagnosis, and
+		// {@link Smoke.dnsHint} still has to recognise an ENOTFOUND inside it.
+		const response = await send(url.toString(), {
+			redirect: "manual",
+			signal: AbortSignal.timeout(timeoutMs),
+			headers: { accept: "text/html" },
+		}).catch((thrown: unknown) => {
+			const failed = thrown as Error;
+			throw new Error(`${address} could not be reached — ${failed.message}`);
+		});
+		if (response.status !== 200) {
+			problems.push(`${address} answered ${response.status} for ${path}`);
+			shells.push({ address, assets: [] });
+			continue;
+		}
+		const assets = builtAssetsIn(await response.text(), address);
+		if (assets.length === 0) problems.push(`${address} served a shell naming no built assets`);
+		shells.push({ address, assets });
+	}
+
+	const named = (shell: AddressShell) => `${shell.address} → ${shell.assets.join(", ") || "(none)"}`;
+	if (problems.length > 0) {
+		return { agreed: false, detail: `${problems.join("; ")} — ${shells.map(named).join(" | ")}`, shells };
+	}
+
+	const distinct = new Set(shells.map((shell) => shell.assets.join(",")));
+	if (distinct.size > 1) {
+		return {
+			agreed: false,
+			detail:
+				`the addresses of one deployment serve DIFFERENT built assets — ${shells.map(named).join(" | ")}.` +
+				" Something in front of this app is answering with bytes this checkout did not build.",
+			shells,
+		};
+	}
+
+	return { agreed: true, detail: `${shells.length} addresses agree — ${shells[0]?.assets.join(", ")}`, shells };
+}
+
+/** The check's name in the ledger. Exported so a caller can talk about its own result. */
+export const SAME_SHELL_CHECK = "every address serves the same built client";
+
+/**
+ * {@link compareDeployedShells}, recorded — and an EDGE fault when it disagrees.
+ *
+ * 🔴 **Code 2, deliberately: a disagreement is never a reason to roll back.** The
+ * origin in that comparison is serving what this checkout built; what is wrong sits
+ * in FRONT of it — a shadowing Worker, a cache rule, a stale Assets binding — and
+ * reverting the application code cannot reach any of them. It would discard the
+ * good deploy and leave the visitor on the same old bytes, which is the failure the
+ * exit-code contract at the top of this file exists to prevent.
+ *
+ * ```ts
+ * await sameDeployedShell(smoke, [smoke.base, `http://127.0.0.1:${port}`]);
+ * ```
+ */
+export async function sameDeployedShell(smoke: Smoke, addresses: string[], options: ShellOptions = {}): Promise<boolean> {
+	let agreed = false;
+	await guarded(smoke, SAME_SHELL_CHECK, async () => {
+		const agreement = await compareDeployedShells(addresses, options);
+		agreed = smoke.record(SAME_SHELL_CHECK, agreement.agreed, agreement.detail);
+		if (!agreement.agreed) smoke.markEdgeFault();
+	});
+	return agreed;
+}