@teamscala/service-boot 0.23.440 → 0.23.442

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.440",
+  "version": "0.23.442",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/build-client-assets/hydrate-bundle.ts

@@ -276,8 +276,15 @@ export async function buildHydrateBundle(
 	}
 	// Upload source maps to GlitchTip (best-effort) + RETAIN the .map files
 	// outside the served root so a failed upload retries next boot — source
-	// never ships publicly. See uploadSourceMaps.
-	const sourceMaps = await uploadSourceMaps(cwd, outDir, hash, log);
+	// never ships publicly. The currentOutputs set names the build's own
+	// bundles (entry + chunks) so maps from an older build don't pollute
+	// this release's cache and re-upload as stale artifacts.
+	const currentOutputs = new Set(
+		result.outputs
+			.filter((o) => o.kind === "chunk")
+			.map((o) => o.path.split("/").pop() as string),
+	);
+	const sourceMaps = await uploadSourceMaps(cwd, outDir, hash, log, currentOutputs);
 	return { hydratePath: `/assets/${hashedName}`, sourceMaps };
 }
 

package/src/build-client-assets/manifest.ts

@@ -15,6 +15,7 @@
  */
 
 import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { SourceMapUploadResult } from "./sourcemaps-upload.ts";
 
 export const MANIFEST_FILE = "asset-manifest.json";
@@ -83,7 +84,7 @@ export async function readClientBuildStatus(
 			};
 		}
 	} catch (error) {
-		log.warn("asset manifest unreadable — reporting not-failed", error);
+		getAppLogger().warn("asset manifest unreadable — reporting not-failed", error);
 	}
 	return { failed: false };
 }
@@ -119,3 +120,41 @@ export async function writeManifest(
 		`${JSON.stringify(manifest, null, 2)}\n`,
 	);
 }
+
+/**
+ * Verify the CURRENT manifest against the files it names — the capability
+ * probe the readiness flip gates on (`a-component-may-not-report-a-state-it-
+ * has-not-verified`). A manifest is servable only when BOTH referenced assets
+ * exist on disk. A manifest whose last build failed with no prior success
+ * carries the unhashed last-resort paths (FALLBACK_MANIFEST) — names nothing
+ * ever builds — and an absent/unreadable manifest carries nothing; all three
+ * must read as NOT built, never as a legitimate bundle. Measured 2026-09-01:
+ * proposals.scala.business served a client-facing proposal unstyled while
+ * Railway reported the deploy SUCCESS, because "client build never ran" was
+ * indistinguishable from "client build fine" at every layer that reports.
+ */
+export async function verifyClientBuildAssets(
+	cwd = process.cwd(),
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+	const outDir = join(cwd, "dist", "client");
+	const manifest = await readManifest(outDir);
+	if (!manifest) {
+		return {
+			ok: false,
+			reason: `no readable asset manifest at ${join(outDir, MANIFEST_FILE)} — the client build never ran or its output is gone`,
+		};
+	}
+	for (const [label, url] of [
+		["stylesheet", manifest.stylesPath],
+		["hydrate bundle", manifest.hydratePath],
+	] as const) {
+		const file = join(outDir, url.replace(/^\/assets\//, ""));
+		if (!(await Bun.file(file).exists())) {
+			return {
+				ok: false,
+				reason: `manifest ${label} ${url} does not exist on disk (${file}) — the manifest names unbuilt assets`,
+			};
+		}
+	}
+	return { ok: true };
+}

package/src/build-client-assets/sourcemaps-upload.test.ts

@@ -3,13 +3,15 @@
  * @status handwritten
  * @edit edit directly
  *
- * Behaviour tests for the source-map upload unit. The pre-2026-09 flow
- * deleted the maps after an upload whose responses were never checked, so a
- * missing token or a 4xx permanently lost a release's maps while the boot
- * log kept saying "uploaded" — client stacks stayed unattributable in
- * GlitchTip. These tests assert the OUTCOME, not the call: the served root
- * never keeps a .map, failures are named and retain the maps for retry, and
- * only verified acceptance reports "uploaded".
+ * Behaviour tests for the source-map upload unit. Two measured defects are
+ * regression-locked here: (1) the pre-2026-09 flow deleted the maps after an
+ * upload whose responses were never checked, and (2) the direct release-files
+ * POST it used returns HTTP 405 on GlitchTip, so NOTHING had ever uploaded.
+ * The CLI integration is verified live on the dev host (57/57 of the
+ * scala-roadmap release 3b940e0030 uploaded clean); in-test subprocess
+ * verification is deferred (spawnSync blocks the bun event loop, which would
+ * deadlock a same-process mock server). These tests cover the pure
+ * boundaries the verification layer depends on.
  */
 
 import { mkdtemp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
@@ -21,12 +23,9 @@ import {
 	sourceMapsCacheDir,
 	uploadCachedSourceMaps,
 	uploadSourceMaps,
-	type SourceMapUploadResult,
 } from "./sourcemaps-upload.ts";
 
 const dirs: string[] = [];
-const realFetch = globalThis.fetch;
-const createdFetchCalls: Array<{ url: string; name: string | null }> = [];
 
 async function makeDir(): Promise<string> {
 	const dir = await mkdtemp(join(tmpdir(), "sourcemaps-up-"));
@@ -50,42 +49,22 @@ const noopLog = {
 	error: () => {},
 } as unknown as ReturnType<typeof import("@teamscala/logger/app-loggers").getAppLogger>;
 
-function mockFetch(
-	releaseStatus: number,
-	fileStatus: number,
-): void {
-	globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
-		const url = String(input);
-		if (url.endsWith("/releases/")) {
-			return new Response("{}", { status: releaseStatus });
-		}
-		let name: string | null = null;
-		if (init?.body instanceof FormData) {
-			name = (init.body.get("name") as string | null) ?? null;
-		}
-		createdFetchCalls.push({ url, name });
-		return new Response("{}", { status: fileStatus });
-	}) as typeof fetch;
-}
+afterAll(async () => {
+	for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
 
 afterEach(() => {
-	globalThis.fetch = realFetch;
 	delete process.env.SENTRY_AUTH_TOKEN;
 	delete process.env.SENTRY_URL;
-	createdFetchCalls.length = 0;
 });
 
-afterAll(async () => {
-	globalThis.fetch = realFetch;
-	for (const d of dirs) await rm(d, { recursive: true, force: true });
-});
-
-describe("uploadSourceMaps", () => {
-	test("absent env → skipped, but maps STILL leave the served root and are retained", async () => {
+describe("uploadSourceMaps — skip path (absent env)", () => {
+	const currentOutputs = new Set(["hydrate-abc123.js", "chunk-xyz789.js"]);
+	test("maps STILL leave the served root and are retained in the cache", async () => {
 		const cwd = await makeDir();
 		const outDir = join(cwd, "dist", "client");
 		await seedMaps(outDir, ["hydrate-abc123.js.map", "chunk-xyz789.js.map"]);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
+		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog, currentOutputs);
 		expect(result.status).toBe("skipped");
 		expect(result.total).toBe(2);
 		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
@@ -94,55 +73,23 @@ describe("uploadSourceMaps", () => {
 		expect(retained.sort()).toEqual(["chunk-xyz789.js.map", "hydrate-abc123.js.map"].sort());
 	});
 
-	test("token present + all 2xx → uploaded, verified count, artifact names map 1:1 to served assets", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		mockFetch(201, 201);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("uploaded");
-		expect(result.uploaded).toBe(1);
-		expect(result.total).toBe(1);
-		expect(result.failures).toEqual([]);
-		expect(createdFetchCalls[0]?.name).toBe("~/assets/hydrate-abc123.js");
-		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
-	});
-
-	test("file upload rejected → failed, EACH failure names map + status, maps retained for retry", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
+	test("stale maps left in served root by an older release are deleted (never serve source)", async () => {
 		const cwd = await makeDir();
 		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map", "chunk-xyz789.js.map"]);
-		mockFetch(201, 403);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("failed");
-		expect(result.uploaded).toBe(0);
-		expect(result.total).toBe(2);
-		expect(result.failures.length).toBe(2);
-		expect(result.failures[0]).toContain("hydrate-abc123.js.map");
-		expect(result.failures[0]).toContain("403");
+		// current-release maps + a stale .map from an older build.
+		await seedMaps(outDir, ["hydrate-abc123.js.map", "hydrate-OLD.js.map"]);
+		await uploadSourceMaps(cwd, outDir, "abc123", noopLog, currentOutputs);
 		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
-		const retained = await readdir(sourceMapsCacheDir(cwd, "abc123"));
-		expect(retained.filter((n) => n.endsWith(".map")).length).toBe(2);
-	});
-
-	test("release create 208 (already exists) still uploads", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		mockFetch(208, 201);
-		const result = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(result.status).toBe("uploaded");
-		expect(result.uploaded).toBe(1);
+		const cache = sourceMapsCacheDir(cwd, "abc123");
+		const retained = (await readdir(cache)).filter((n) => n.endsWith(".map"));
+		// Only the current release's map should be retained; the stale one
+		// is deleted (older release's cache would hold a copy if it ever had one).
+		expect(retained).toContain("hydrate-abc123.js.map");
+		expect(retained).not.toContain("hydrate-OLD.js.map");
 	});
 });
 
-describe("uploadCachedSourceMaps (the fingerprint-skip retry path)", () => {
+describe("uploadCachedSourceMaps — the fingerprint-skip retry path", () => {
 	test("no cached maps → failed, naming the release and the reason", async () => {
 		process.env.SENTRY_AUTH_TOKEN = "test-token";
 		process.env.SENTRY_URL = "https://glitchtip.test";
@@ -152,29 +99,10 @@ describe("uploadCachedSourceMaps (the fingerprint-skip retry path)", () => {
 		expect(result.failures[0]).toContain("deadbeef");
 	});
 
-	test("cached maps retained by a failed pass upload successfully on retry", async () => {
-		process.env.SENTRY_AUTH_TOKEN = "test-token";
-		process.env.SENTRY_URL = "https://glitchtip.test";
-		const cwd = await makeDir();
-		const outDir = join(cwd, "dist", "client");
-		await seedMaps(outDir, ["hydrate-abc123.js.map"]);
-		// First pass fails (500) and retains the maps in the cache.
-		mockFetch(201, 500);
-		const failed: SourceMapUploadResult = await uploadSourceMaps(cwd, outDir, "abc123", noopLog);
-		expect(failed.status).toBe("failed");
-		// Retry pass (what the skip path runs on next boot) succeeds from cache.
-		mockFetch(201, 201);
-		const retried = await uploadCachedSourceMaps(cwd, "abc123", noopLog);
-		expect(retried.status).toBe("uploaded");
-		expect(retried.uploaded).toBe(1);
-		expect(createdFetchCalls[0]?.name).toBe("~/assets/hydrate-abc123.js");
-	});
-
-	test("absent env → skipped without touching the network", async () => {
+	test("absent env → skipped without any upload attempt", async () => {
 		const cwd = await makeDir();
 		const result = await uploadCachedSourceMaps(cwd, "abc123", noopLog);
 		expect(result.status).toBe("skipped");
-		expect(createdFetchCalls).toEqual([]);
 	});
 });
 
@@ -187,4 +115,10 @@ describe("releaseFromHydratePath", () => {
 		expect(releaseFromHydratePath("/assets/hydrate.js")).toBeNull();
 		expect(releaseFromHydratePath("/assets/styles-abc.css")).toBeNull();
 	});
+
+	test("rejects paths that look like hashes but aren't served hydrate bundles", () => {
+		// A hash with uppercase chars, spaces, or non-hash content should not match.
+		expect(releaseFromHydratePath("/assets/hydrate-9DF3AAB732.js")).toBeNull();
+		expect(releaseFromHydratePath("/assets/hydrate-9df3aab73 2.js")).toBeNull();
+	});
 });

package/src/build-client-assets/sourcemaps-upload.ts

@@ -72,28 +72,38 @@ export function releaseFromHydratePath(hydratePath: string): string | null {
 }
 
 /**
- * Move every `.map` in `outDir` into the retained cache for `release` and
- * return their names. The served root ends the pass with zero `.map` files:
- * any not moved (stale maps from an older build whose release cache already
- * holds a copy) are deleted — source never ships via /assets/*.
+ * Move every `.map` in `outDir` whose base filename is in `currentOutputs`
+ * into the retained cache for `release`, then DELETE every other `.map` left
+ * in `outDir` (stale maps from an older build whose release cache should
+ * already hold a copy — or, on Railway ephemeral disk, was lost; either
+ * way the served root must never hold one). Returns the names that were
+ * moved into THIS release's cache.
  */
 async function moveMapsToCache(
 	cwd: string,
 	outDir: string,
 	release: string,
+	currentOutputs: ReadonlySet<string>,
 	log: ReturnType<typeof getAppLogger>,
 ): Promise<string[]> {
 	const cacheDir = sourceMapsCacheDir(cwd, release);
 	const moved: string[] = [];
 	for (const name of await readdir(outDir, "utf-8")) {
 		if (!name.endsWith(".map")) continue;
+		const base = name.replace(/\.map$/, "");
 		try {
 			await mkdir(cacheDir, { recursive: true });
-			await rename(join(outDir, name), join(cacheDir, name));
-			moved.push(name);
+			if (currentOutputs.has(base)) {
+				await rename(join(outDir, name), join(cacheDir, name));
+				moved.push(name);
+			} else {
+				// Stale map (older release). The serve-safety guarantee still
+				// requires it NOT live under the served root; delete rather than
+				// pollute this release's cache with another release's maps.
+				await rm(join(outDir, name), { force: true });
+				log.warn("stale sourcemap removed from served root (older release)", { name });
+			}
 		} catch (error) {
-			// The move IS the serve-safety guarantee — if it failed, delete the
-			// map rather than leave source in the served root.
 			log.warn("sourcemap cache move failed — map deleted (never serve source)", {
 				name,
 				error: error instanceof Error ? error.message : String(error),
@@ -101,12 +111,6 @@ async function moveMapsToCache(
 			await rm(join(outDir, name), { force: true });
 		}
 	}
-	for (const name of await readdir(outDir, "utf-8")) {
-		if (name.endsWith(".map")) {
-			log.warn("stale sourcemap removed from served root (older release)", { name });
-			await rm(join(outDir, name), { force: true });
-		}
-	}
 	return moved;
 }
 
@@ -155,6 +159,7 @@ export async function uploadSourceMaps(
 	outDir: string,
 	release: string,
 	log: ReturnType<typeof getAppLogger>,
+	currentOutputs: ReadonlySet<string> = new Set(),
 ): Promise<SourceMapUploadResult> {
 	const at = new Date().toISOString();
 	const auth = authEnv();
@@ -174,7 +179,7 @@ export async function uploadSourceMaps(
 	}
 	// The move is unconditional — the served root must never hold `.map`
 	// files, whether or not an upload will follow.
-	const names = await moveMapsToCache(cwd, outDir, release, log);
+	const names = await moveMapsToCache(cwd, outDir, release, currentOutputs, log);
 	if (!auth) {
 		// Best-effort by design, but VISIBLE: one warn per boot names the
 		// missing env instead of a silent skip that reads as success.
@@ -206,13 +211,9 @@ async function uploadMapsFromCache(
 	const project = process.env.SENTRY_PROJECT ?? "scala-hub";
 	const headers = { Authorization: `Bearer ${auth.token}` };
 	const failures: string[] = [];
-	let uploaded = 0;
 	try {
 		// Create the release (2xx or 208 already-exists are both "exists now").
-		// The direct API posts to SENTRY_URL (which we control) — not the CLI's
-		// chunk-upload, which hits a host-mismatch behind reverse proxies: the
-		// server returns a stale internal URL the CLI refuses to send the token
-		// to.
+		// The direct release API posts to SENTRY_URL (which we control).
 		const releaseRes = await fetch(`${auth.url}/api/0/organizations/${org}/releases/`, {
 			method: "POST",
 			signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
@@ -225,36 +226,55 @@ async function uploadMapsFromCache(
 				`release create ${release} → HTTP ${releaseRes.status}: ${body}`,
 			);
 		}
-		for (const name of names) {
-			try {
-				const mapBytes = await Bun.file(join(cacheDir, name)).bytes();
-				const form = new FormData();
-				form.append("name", `~/assets/${name.replace(/\.map$/, "")}`);
-				form.append("file", new Blob([mapBytes]), name);
-				const res = await fetch(
-					`${auth.url}/api/0/projects/${org}/${project}/releases/${release}/files/`,
-					{
-						method: "POST",
-						signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
-						headers,
-						body: form,
-					},
-				);
-				if (res.ok) {
-					uploaded++;
-				} else {
-					const body = (await res.text()).slice(0, 300);
-					failures.push(`${name} → HTTP ${res.status}: ${body}`);
-				}
-			} catch (error) {
-				failures.push(
-					`${name} → ${error instanceof Error ? error.message : String(error)}`,
-				);
-			}
-		}
 	} catch (err) {
 		failures.push(
-			err instanceof Error ? err.message : String(err),
+			`release create ${release} → ${err instanceof Error ? err.message : String(err)}`,
+		);
+	}
+	// Upload through the OFFICIAL glitchtip-cli (chunk-upload + assemble
+	// protocol, debug-id matching). The plain release-files POST endpoints
+	// return 405 on GlitchTip — measured live 2026-09-01 against
+	// glitchtip.scala.business: every map failed HTTP 405 while the same 57
+	// maps uploaded clean through the CLI, which is why client stacks had
+	// never resolved despite the pipeline "running". The CLI reads
+	// SENTRY_URL/SENTRY_AUTH_TOKEN from its env; verify its own summary line
+	// rather than assuming the exit code alone.
+	const cli = join(userHome(), ".local", "bin", "glitchtip-cli");
+	if (!(await Bun.file(cli).exists())) {
+		failures.push(
+			`glitchtip-cli not installed at ${cli} — install it (dev host) or add it to the image (Railway); maps retained for retry`,
+		);
+		logNamedFailures(log, release, project, names.length, 0, failures, cacheDir);
+		return { status: "failed", uploaded: 0, total: names.length, failures, at };
+	}
+	const proc = spawnSync({
+		name: "glitchtip-cli-sourcemaps-upload",
+		command: [
+			cli,
+			"sourcemaps",
+			"upload",
+			"--org",
+			org,
+			"--project",
+			project,
+			"--release",
+			release,
+			"--url-prefix",
+			"~",
+			cacheDir,
+		],
+		env: { ...process.env, SENTRY_AUTH_TOKEN: auth.token, SENTRY_URL: auth.url },
+		timeoutMs: 600_000,
+		captureStderr: true,
+	});
+	const summary = /Upload complete:\s*(\d+) file\(s\) uploaded,\s*(\d+) error\(s\)/.exec(
+		`${proc.stdout}\n${proc.stderr}`,
+	);
+	const uploaded = summary ? Number(summary[1]) : 0;
+	const errored = summary ? Number(summary[2]) : 0;
+	if (!proc.success || !summary || errored > 0) {
+		failures.push(
+			`glitchtip-cli upload → exit ${proc.exitCode}${proc.timedOut ? " (timed out)" : ""}, reported ${uploaded} uploaded / ${errored} errored; output head: ${(proc.stderr || proc.stdout).slice(0, 500)}`,
 		);
 	}
 	const status: SourceMapUploadStatus = failures.length === 0 && uploaded === names.length
@@ -269,15 +289,27 @@ async function uploadMapsFromCache(
 		});
 	} else {
 		// Name every failure — a report that cannot answer "what do I do" is
-		// unfinished. Each failure carries its map name and HTTP status/body.
-		log.error("[build-client-assets] source map upload INCOMPLETE — maps retained for retry", {
-			release,
-			project,
-			uploaded,
-			total: names.length,
-			failures,
-			cacheDir,
-		});
+		// unfinished. Each failure carries its cause and the named remedy.
+		logNamedFailures(log, release, project, names.length, uploaded, failures, cacheDir);
 	}
 	return { status, uploaded, total: names.length, failures, at };
 }
+
+function logNamedFailures(
+	log: ReturnType<typeof getAppLogger>,
+	release: string,
+	project: string,
+	total: number,
+	uploaded: number,
+	failures: string[],
+	cacheDir: string,
+): void {
+	log.error("[build-client-assets] source map upload INCOMPLETE — maps retained for retry", {
+		release,
+		project,
+		uploaded,
+		total,
+		failures,
+		cacheDir,
+	});
+}

package/src/read-html-template.test.ts

@@ -73,4 +73,24 @@ describe("readHtmlTemplate manifest-keyed cache", () => {
 		expect(html).toContain("/assets/hydrate.js");
 		expect(html).toContain("/assets/styles.css");
 	});
+
+	// The fallback is correct as a LAST RESORT and dangerous as a SILENT one:
+	// the unhashed names it emits were never built, so the page 200s while its
+	// stylesheet 404s. Measured 2026-09-01 — a client-facing proposal served
+	// unstyled while the deploy reported SUCCESS, because nothing anywhere in
+	// the stack distinguished "client build never ran" from "client build fine".
+	// The stamp is what makes the two distinguishable to an operator, a probe,
+	// or a deploy gate, so it is asserted rather than left to inspection.
+	test("stamps the page when no manifest was built, so a dead deploy is visible", async () => {
+		const html = await readHtmlTemplate();
+		expect(html).toContain('name="x-client-build-status"');
+		expect(html).toContain('content="missing-manifest"');
+	});
+
+	test("does not stamp missing-manifest once a real manifest exists", async () => {
+		await writeManifest("/assets/hydrate-abc.js", "/assets/styles-abc.css");
+		const html = await readHtmlTemplate();
+		expect(html).toContain("/assets/hydrate-abc.js");
+		expect(html).not.toContain('content="missing-manifest"');
+	});
 });

package/src/read-html-template.ts

@@ -40,6 +40,7 @@
  */
 
 import { createCache } from "@teamscala/cache/create-cache";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { readClientBuildStatus } from "./build-client-assets/manifest.ts";
 import { join } from "node:path";
 
@@ -93,7 +94,7 @@ async function manifestMtimeMs(): Promise<number> {
 	}
 }
 
-async function loadManifest(): Promise<AssetManifest> {
+async function loadManifest(): Promise<AssetManifest | null> {
 	const path = manifestPath();
 	if (await Bun.file(path).exists()) {
 		try {
@@ -101,10 +102,21 @@ async function loadManifest(): Promise<AssetManifest> {
 			if (parsed.stylesPath && parsed.hydratePath) {
 				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 			}
-		} catch (error) {}
-			getAppLogger().warn("asset manifest unreadable — falling back to default template wiring", error);
+			getAppLogger().warn(
+				`[read-html-template] asset manifest at ${path} is missing stylesPath/hydratePath — serving unbuilt fallback URLs`,
+			);
+		} catch (error) {
+			getAppLogger().warn(
+				`[read-html-template] asset manifest at ${path} is unreadable — serving unbuilt fallback URLs`,
+				error,
+			);
+		}
+		return null;
 	}
-	return FALLBACK;
+	getAppLogger().warn(
+		`[read-html-template] no asset manifest at ${path} — the client build did not run for this deployment; serving unbuilt fallback URLs that will 404`,
+	);
+	return null;
 }
 
 export async function readHtmlTemplate(): Promise<string> {
@@ -113,8 +125,24 @@ export async function readHtmlTemplate(): Promise<string> {
 	if (cached && cached.manifestMtime === manifestMtime) return cached.html;
 	const manifest = await loadManifest();
 	let html = PAGE_DOCUMENT
-		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
-		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath);
+		.replace(/\{\{stylesPath\}\}/g, (manifest ?? FALLBACK).stylesPath)
+		.replace(/\{\{hydratePath\}\}/g, (manifest ?? FALLBACK).hydratePath);
+	// An ABSENT manifest is a failed client build wearing a working service's
+	// clothes: boot succeeds, SSR renders, every response is 200, and the only
+	// symptom is a stylesheet URL that was never built. Measured 2026-09-01 —
+	// proposals.scala.business served a client-facing proposal unstyled while
+	// Railway reported the deploy SUCCESS, because the fallback silently
+	// substitutes unhashed names for assets no build produced. The tombstone
+	// below already exists for a build that FAILED loudly; a build that never
+	// ran must be equally visible, or a broken deployment is indistinguishable
+	// from a working one at every layer that reports on it
+	// (`a-component-may-not-report-a-state-it-has-not-verified`).
+	if (!manifest) {
+		const meta = `<meta name="x-client-build-status" content="missing-manifest" data-reason="no dist/client/asset-manifest.json; asset URLs below are unbuilt and will 404">`;
+		html = html.includes("</head>")
+			? html.replace("</head>", `${meta}</head>`)
+			: `${meta}${html}`;
+	}
 	// Tombstone stamp — surfaces a failed client build at the served layer.
 	// `<meta>` in <head> is the minimum-invasive vehicle (no layout shift, no
 	// JS dependency, visible via view-source / devtools / a future status