@teamscala/service-boot 0.23.436 → 0.23.438

package/package.json

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

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

@@ -59,14 +59,24 @@ import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { fileHash, removeStaleHashedFiles } from "./hashed-output.ts";
-import { uploadSourceMaps } from "./sourcemaps-upload.ts";
+import {
+	uploadSourceMaps,
+	type SourceMapUploadResult,
+} from "./sourcemaps-upload.ts";
 
 const HYDRATE_BASE = "hydrate";
 
+export interface HydrateBundleResult {
+	/** Served entry path (`/assets/hydrate-<hash>.js`), or null when no entry exists. */
+	hydratePath: string | null;
+	/** The VERIFIED source-map upload outcome for this build's release. */
+	sourceMaps: SourceMapUploadResult;
+}
+
 export async function buildHydrateBundle(
 	cwd: string,
 	log: ReturnType<typeof getAppLogger>,
-): Promise<string | null> {
+): Promise<HydrateBundleResult | null> {
 	const entry = join(cwd, "src", "entry-client.ts");
 	const outDir = join(cwd, "dist", "client");
 	const tmpFile = join(outDir, `${HYDRATE_BASE}.js`);
@@ -264,10 +274,11 @@ export async function buildHydrateBundle(
 			{ externalizedBlocks },
 		);
 	}
-	// Upload source maps to GlitchTip (best-effort, dev-host-only) + delete the
-	// .map files so source never ships publicly. See uploadSourceMaps.
-	await uploadSourceMaps(outDir, hash, log);
-	return `/assets/${hashedName}`;
+	// 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);
+	return { hydratePath: `/assets/${hashedName}`, sourceMaps };
 }
 
 // Remove hashed code-split chunks no longer referenced by the current entry.

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

@@ -15,6 +15,7 @@
  */
 
 import { join } from "node:path";
+import type { SourceMapUploadResult } from "./sourcemaps-upload.ts";
 
 export const MANIFEST_FILE = "asset-manifest.json";
 
@@ -42,6 +43,13 @@ export interface AssetManifest {
 	buildFailed?: boolean;
 	buildFailedReason?: string;
 	buildFailedAt?: string;
+	// VERIFIED outcome of the last source-map upload attempt for THIS build's
+	// release (`uploaded` = every response checked 2xx; `failed` names each
+	// rejection in `failures`; `skipped` = no SENTRY_AUTH_TOKEN/SENTRY_URL).
+	// The fingerprint-skip path reads it: any status other than `uploaded`
+	// re-runs the upload from the retained map cache on every boot until it
+	// verifies — an unuploaded release must not silently persist forever.
+	sourceMaps?: SourceMapUploadResult;
 }
 
 // Last-resort paths for a tombstone when no prior successful manifest exists
@@ -93,6 +101,7 @@ export async function readManifest(outDir: string): Promise<AssetManifest | null
 				buildFailed: parsed.buildFailed,
 				buildFailedReason: parsed.buildFailedReason,
 				buildFailedAt: parsed.buildFailedAt,
+				sourceMaps: parsed.sourceMaps,
 			};
 		}
 		return null;

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

@@ -0,0 +1,190 @@
+/**
+ * @system server-handlers
+ * @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".
+ */
+
+import { mkdtemp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, test } from "bun:test";
+import {
+	releaseFromHydratePath,
+	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-"));
+	dirs.push(dir);
+	return dir;
+}
+
+async function seedMaps(outDir: string, names: string[]): Promise<void> {
+	await mkdir(outDir, { recursive: true });
+	for (const name of names) {
+		await writeFile(
+			join(outDir, name),
+			JSON.stringify({ version: 3, sources: ["a.ts"], mappings: "AAAA" }),
+		);
+	}
+}
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	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;
+}
+
+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 () => {
+		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);
+		expect(result.status).toBe("skipped");
+		expect(result.total).toBe(2);
+		expect((await readdir(outDir)).filter((n) => n.endsWith(".map"))).toEqual([]);
+		const cache = sourceMapsCacheDir(cwd, "abc123");
+		const retained = (await readdir(cache)).filter((n) => n.endsWith(".map"));
+		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";
+		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");
+		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);
+	});
+});
+
+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";
+		const cwd = await makeDir();
+		const result = await uploadCachedSourceMaps(cwd, "deadbeef", noopLog);
+		expect(result.status).toBe("failed");
+		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 () => {
+		const cwd = await makeDir();
+		const result = await uploadCachedSourceMaps(cwd, "abc123", noopLog);
+		expect(result.status).toBe("skipped");
+		expect(createdFetchCalls).toEqual([]);
+	});
+});
+
+describe("releaseFromHydratePath", () => {
+	test("extracts the bare content hash from a manifest hydratePath", () => {
+		expect(releaseFromHydratePath("/assets/hydrate-9df3aab732.js")).toBe("9df3aab732");
+	});
+
+	test("non-hydrate paths yield null (no proximity guess)", () => {
+		expect(releaseFromHydratePath("/assets/hydrate.js")).toBeNull();
+		expect(releaseFromHydratePath("/assets/styles-abc.css")).toBeNull();
+	});
+});

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

@@ -4,7 +4,8 @@
  * @edit edit directly
  *
  * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
- * flow, then delete the .map files so source never ships publicly.
+ * flow, then RETAIN the maps outside the served root so a failed upload is
+ * retryable on a later boot.
  *
  * Split out of build-client-assets.ts (962 lines) alongside its build
  * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
@@ -17,89 +18,266 @@
  * `sourcemaps upload --release`; see telemetry.md `client-errors-report-to-glitchtip`
  * + https://glitchtip.com/documentation/cli). Debug IDs injected into the served
  * bundles + uploaded maps are the matching mechanism — robust vs URL-prefix
- * guessing. Best-effort + dev-host-only: skips silently when the CLI or
- * SENTRY_AUTH_TOKEN is absent (Railway builds don't install the CLI; prod source
- * maps are a follow-up). The .map files are deleted after upload — source never
- * ships publicly; the debug IDs in the served bundles are all the SDK needs.
+ * guessing.
+ *
+ * THE MAPS OUTLIVE THE UPLOAD ATTEMPT: `.map` files are MOVED out of the
+ * served root (`dist/client/` — /assets/* would serve source publicly) into
+ * the retained cache `dist/sourcemaps/<release>/` BEFORE anything else, and
+ * the upload runs from the cache. A failed or skipped upload therefore
+ * leaves the maps on disk for the next boot's retry (the fingerprint-skip
+ * path in build-client-assets.ts re-runs the upload whenever the manifest
+ * does not record `uploaded`) instead of destroying the only copy of a
+ * release's maps on an unverified claim (`a-component-may-not-report-a-
+ * state-it-has-not-verified`; measured: 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").
+ *
+ * Every upstream response is verified: the release-create call must return
+ * 2xx/208 and each file upload must return 2xx, else the failure is named
+ * (status + body head) in the result. Best-effort at the SERVICE level — a
+ * failed upload never blocks boot — but never at the CLAIM level: the
+ * result says what actually happened and the manifest records it.
  */
 
-import { readdir, rm } from "node:fs/promises";
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { userHome } from "@teamscala/os/host-paths";
 import { spawnSync } from "@teamscala/os/spawn";
 
-export async function uploadSourceMaps(
+export type SourceMapUploadStatus = "uploaded" | "failed" | "skipped";
+
+export interface SourceMapUploadResult {
+	status: SourceMapUploadStatus;
+	/** Maps verified accepted by GlitchTip (2xx), never assumed. */
+	uploaded: number;
+	/** Maps present for this upload pass (moved to the retained cache). */
+	total: number;
+	/** One named failure per non-accepted upload (status + body head). */
+	failures: string[];
+	at: string;
+}
+
+const UPLOAD_TIMEOUT_MS = 30_000;
+
+/** The retained, never-served home of a release's source maps. */
+export function sourceMapsCacheDir(cwd: string, release: string): string {
+	return join(cwd, "dist", "sourcemaps", release);
+}
+
+/** The release (bare content hash) a manifest's hydratePath names. */
+export function releaseFromHydratePath(hydratePath: string): string | null {
+	return /hydrate-([a-z0-9]+)\.js/.exec(hydratePath)?.[1] ?? 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/*.
+ */
+async function moveMapsToCache(
+	cwd: string,
 	outDir: string,
 	release: string,
 	log: ReturnType<typeof getAppLogger>,
-): Promise<void> {
+): Promise<string[]> {
+	const cacheDir = sourceMapsCacheDir(cwd, release);
+	const moved: string[] = [];
+	for (const name of await readdir(outDir, "utf-8")) {
+		if (!name.endsWith(".map")) continue;
+		try {
+			await mkdir(cacheDir, { recursive: true });
+			await rename(join(outDir, name), join(cacheDir, name));
+			moved.push(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),
+			});
+			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;
+}
+
+function authEnv(): { token: string; url: string } | null {
 	const token = process.env.SENTRY_AUTH_TOKEN;
-	const sentryUrl = process.env.SENTRY_URL;
-	if (!token || !sentryUrl) return; // best-effort: no token/URL → skip
+	const url = process.env.SENTRY_URL;
+	if (!token || !url) return null;
+	return { token, url };
+}
+
+/** Upload the maps ALREADY RETAINED in the cache for `release`. */
+export async function uploadCachedSourceMaps(
+	cwd: string,
+	release: string,
+	log: ReturnType<typeof getAppLogger>,
+): Promise<SourceMapUploadResult> {
+	const at = new Date().toISOString();
+	const auth = authEnv();
+	const cacheDir = sourceMapsCacheDir(cwd, release);
+	if (!auth) {
+		return { status: "skipped", uploaded: 0, total: 0, failures: [], at };
+	}
+	let names: string[] = [];
+	try {
+		names = (await readdir(cacheDir, "utf-8")).filter((n) => n.endsWith(".map"));
+	} catch {
+		names = [];
+	}
+	if (names.length === 0) {
+		return {
+			status: "failed",
+			uploaded: 0,
+			total: 0,
+			failures: [
+				`no cached source maps for release ${release} at ${cacheDir} — the build that produced them predates retention or they were removed; next bundle rebuild regenerates them`,
+			],
+			at,
+		};
+	}
+	return uploadMapsFromCache(cacheDir, names, release, auth, log, at);
+}
+
+/** Upload source maps for the bundle just built into `outDir`. */
+export async function uploadSourceMaps(
+	cwd: string,
+	outDir: string,
+	release: string,
+	log: ReturnType<typeof getAppLogger>,
+): Promise<SourceMapUploadResult> {
+	const at = new Date().toISOString();
+	const auth = authEnv();
+	// Inject debug IDs into the served bundles + maps (if glitchtip-cli is
+	// present). Runs on outDir BEFORE the cache move so both the served
+	// bundle and its retained map carry the same debug id. The CLI is
+	// optional — only used for the inject step.
+	const cli = join(userHome(), ".local", "bin", "glitchtip-cli");
+	if (await Bun.file(cli).exists()) {
+		spawnSync({
+			name: "glitchtip-cli-sourcemaps-inject",
+			command: [cli, "sourcemaps", "inject", outDir],
+			env: { ...process.env, SENTRY_AUTH_TOKEN: auth?.token ?? "" },
+			timeoutMs: 60_000,
+			captureStderr: true,
+		});
+	}
+	// 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);
+	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.
+		log.warn(
+			`[build-client-assets] source maps NOT uploaded — SENTRY_AUTH_TOKEN/SENTRY_URL absent (maps retained at ${sourceMapsCacheDir(cwd, release)} for retry once configured)`,
+			{ release, mapsRetained: names.length },
+		);
+		return { status: "skipped", uploaded: 0, total: names.length, failures: [], at };
+	}
+	return uploadMapsFromCache(
+		sourceMapsCacheDir(cwd, release),
+		names,
+		release,
+		auth,
+		log,
+		at,
+	);
+}
+
+async function uploadMapsFromCache(
+	cacheDir: string,
+	names: string[],
+	release: string,
+	auth: { token: string; url: string },
+	log: ReturnType<typeof getAppLogger>,
+	at: string,
+): Promise<SourceMapUploadResult> {
 	const org = process.env.SENTRY_ORG ?? "scala";
 	const project = process.env.SENTRY_PROJECT ?? "scala-hub";
-	const cli = join(userHome(), ".local", "bin", "glitchtip-cli");
-	const headers = { Authorization: `Bearer ${token}` };
+	const headers = { Authorization: `Bearer ${auth.token}` };
+	const failures: string[] = [];
+	let uploaded = 0;
 	try {
-		// Inject debug IDs into the bundles + maps (if glitchtip-cli is present).
-		// The CLI is optional — only used for the inject step.
-		if (await Bun.file(cli).exists()) {
-			spawnSync({
-				name: "glitchtip-cli-sourcemaps-inject",
-				command: [cli, "sourcemaps", "inject", outDir],
-				env: { ...process.env, SENTRY_AUTH_TOKEN: token },
-				timeoutMs: 60_000,
-				captureStderr: true,
-			});
-		}
-		// Upload source maps via the direct release-files API (NOT the CLI's
-		// chunk-upload — that hits a host-mismatch behind reverse proxies: the
-		// server returns a stale internal URL the CLI refuses to send the token to).
-		// The direct API posts to SENTRY_URL (which we control) — no server-returned
-		// URL, no host mismatch.
-		await fetch(`${sentryUrl}/api/0/organizations/${org}/releases/`, {
+		// 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.
+		const releaseRes = await fetch(`${auth.url}/api/0/organizations/${org}/releases/`, {
 			method: "POST",
+			signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
 			headers: { ...headers, "Content-Type": "application/json" },
 			body: JSON.stringify({ version: release, projects: [project] }),
 		});
-		let uploaded = 0;
-		for (const name of await readdir(outDir, "utf-8")) {
-			if (!name.endsWith(".map")) continue;
+		if (!(releaseRes.ok || releaseRes.status === 208)) {
+			const body = (await releaseRes.text()).slice(0, 300);
+			failures.push(
+				`release create ${release} → HTTP ${releaseRes.status}: ${body}`,
+			);
+		}
+		for (const name of names) {
 			try {
-				const mapBytes = await Bun.file(join(outDir, name)).bytes();
+				const mapBytes = await Bun.file(join(cacheDir, name)).bytes();
 				const form = new FormData();
-				form.append("name", `~/assets/${name.replace(".map", "")}`);
+				form.append("name", `~/assets/${name.replace(/\.map$/, "")}`);
 				form.append("file", new Blob([mapBytes]), name);
 				const res = await fetch(
-					`${sentryUrl}/api/0/projects/${org}/${project}/releases/${release}/files/`,
-					{ method: "POST", headers, body: form },
+					`${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++;
+				if (res.ok) {
+					uploaded++;
+				} else {
+					const body = (await res.text()).slice(0, 300);
+					failures.push(`${name} → HTTP ${res.status}: ${body}`);
+				}
 			} catch (error) {
-				log.warn("sourcemap upload failed — remaining maps continue", error);
+				failures.push(
+					`${name} → ${error instanceof Error ? error.message : String(error)}`,
+				);
 			}
 		}
-		log.info("[build-client-assets] source maps uploaded to GlitchTip", {
+	} catch (err) {
+		failures.push(
+			err instanceof Error ? err.message : String(err),
+		);
+	}
+	const status: SourceMapUploadStatus = failures.length === 0 && uploaded === names.length
+		? "uploaded"
+		: "failed";
+	if (status === "uploaded") {
+		log.info("[build-client-assets] source maps uploaded to GlitchTip (verified)", {
 			release,
 			project,
 			uploaded,
+			total: names.length,
 		});
-	} catch (err) {
-		log.warn("[build-client-assets] source-map upload error (best-effort, skipped)", {
+	} 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,
-			error: err instanceof Error ? err.message : String(err),
+			project,
+			uploaded,
+			total: names.length,
+			failures,
+			cacheDir,
 		});
 	}
-	// Delete the .map files — never serve source. The debug IDs injected into the
-	// served bundles are all the SDK needs; the maps live in GlitchTip keyed by them.
-	for (const name of await readdir(outDir, "utf-8")) {
-		if (name.endsWith(".map")) {
-			try {
-				await rm(join(outDir, name));
-			} catch (error) {
-				getAppLogger().warn("sourcemaps-upload.ts: bare catch around upstream call — logged, continuing (protective-layers-fail-explicitly)", error);
-			}
-		}
-	}
+	return { status, uploaded, total: names.length, failures, at };
 }

package/src/build-client-assets.ts

@@ -64,6 +64,10 @@ import {
 	readManifest,
 	writeManifest,
 } from "./build-client-assets/manifest.ts";
+import {
+	releaseFromHydratePath,
+	uploadCachedSourceMaps,
+} from "./build-client-assets/sourcemaps-upload.ts";
 import { buildTailwindCss } from "./build-client-assets/styles-build.ts";
 
 export async function buildClientAssets(serviceSlug: string): Promise<void> {
@@ -74,7 +78,23 @@ export async function buildClientAssets(serviceSlug: string): Promise<void> {
 	const existingManifest = await readManifest(outDir);
 	const fingerprint = await computeInputFingerprint(cwd);
 	if (existingManifest && existingManifest.inputFingerprint === fingerprint) {
-		log.info(`[build-client-assets:${serviceSlug}] manifest up-to-date (skip)`);
+		// The bundle is fresh, but a fresh bundle with an UNVERIFIED source-map
+		// upload must not stay that way forever: retry the upload from the
+		// retained map cache on every boot until it verifies. Without this, one
+		// failed boot-time upload (GlitchTip down, token missing at that boot)
+		// permanently lost the release's maps — client stacks stayed minified
+		// until the next real input change forced a rebuild.
+		const recorded = existingManifest.sourceMaps?.status;
+		const release = releaseFromHydratePath(existingManifest.hydratePath);
+		if (recorded !== "uploaded" && release) {
+			log.info(
+				`[build-client-assets:${serviceSlug}] manifest up-to-date (skip); source maps previously ${recorded ?? "unrecorded"} — retrying upload for release ${release}`,
+			);
+			const sourceMaps = await uploadCachedSourceMaps(cwd, release, log);
+			await writeManifest(outDir, { ...existingManifest, sourceMaps });
+		} else {
+			log.info(`[build-client-assets:${serviceSlug}] manifest up-to-date (skip)`);
+		}
 		return;
 	}
 	if (existingManifest && existingManifest.inputFingerprint !== fingerprint) {
@@ -177,10 +197,10 @@ async function performBuild(
 		);
 	}
 
-	const hydratePath = hydrateResult.value;
+	const hydrate = hydrateResult.value;
 	const stylesPath = stylesResult.value;
-	if (!hydratePath || !stylesPath) {
-		const reason = `bundle build returned empty path (hydrate=${hydratePath}, styles=${stylesPath})`;
+	if (!hydrate?.hydratePath || !stylesPath) {
+		const reason = `bundle build returned empty path (hydrate=${hydrate?.hydratePath ?? "<null>"}, styles=${stylesPath})`;
 		await writeTombstone(reason);
 		throw new Error(
 			`[build-client-assets:${serviceSlug}] ${reason} — tombstone manifest written.`,
@@ -188,7 +208,12 @@ async function performBuild(
 	}
 
 	await mkdir(outDir, { recursive: true });
-	await writeManifest(outDir, { stylesPath, hydratePath, inputFingerprint });
+	await writeManifest(outDir, {
+		stylesPath,
+		hydratePath: hydrate.hydratePath,
+		inputFingerprint,
+		sourceMaps: hydrate.sourceMaps,
+	});
 
 	log.info(
 		`[build-client-assets:${serviceSlug}] boot-time build complete in ${Date.now() - t0}ms`,

package/src/discover-blocks.ts

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { getPrisma } from "@teamscala/db/prisma-registry";
 import { BlockSchemaConfigSchema } from "@teamscala/db-validation/registry-schemas/block-schema";
 import * as v from "valibot";
+import { isReactElementType } from "./is-react-element-type.ts";
 import type { RendererComponentEntry } from "./types.ts";
 
 export interface DiscoveredBlocks {
@@ -159,7 +160,7 @@ export async function discoverBlocks(
 				),
 			])) as Record<string, unknown>;
 			const component = mod[componentExport] ?? mod.default;
-			if (typeof component !== "function") {
+			if (!isReactElementType(component)) {
 				skipped.push(
 					`${row.slug} (${componentExport} not a component in ${componentPath})`,
 				);

package/src/is-react-element-type.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Pins the three React idioms a `typeof === "function"` check silently rejects.
+ * The memo case is the measured one: PresenceAvatars rendered blank on every
+ * scala-projects page carrying it, because memo() returns an object.
+ */
+
+import { expect, test } from "bun:test";
+import { forwardRef, lazy, memo } from "react";
+import { isReactElementType } from "./is-react-element-type.ts";
+
+function Plain() {
+	return null;
+}
+
+test("accepts a plain function component", () => {
+	expect(isReactElementType(Plain)).toBe(true);
+});
+
+test("accepts memo() — the PresenceAvatars shape that rendered blank", () => {
+	expect(isReactElementType(memo(Plain))).toBe(true);
+});
+
+test("accepts forwardRef()", () => {
+	expect(isReactElementType(forwardRef(() => null))).toBe(true);
+});
+
+test("accepts lazy()", () => {
+	expect(isReactElementType(lazy(async () => ({ default: Plain })))).toBe(true);
+});
+
+test("still rejects what genuinely cannot render", () => {
+	expect(isReactElementType(undefined)).toBe(false);
+	expect(isReactElementType(null)).toBe(false);
+	expect(isReactElementType({})).toBe(false);
+	expect(isReactElementType("PresenceAvatarsBlock")).toBe(false);
+	expect(isReactElementType(42)).toBe(false);
+});
+
+test("rejects a plain object wearing a non-symbol $$typeof", () => {
+	// A data blob with the key but not the symbol must not pass as renderable.
+	expect(isReactElementType({ $$typeof: "react.memo" })).toBe(false);
+});

package/src/is-react-element-type.ts

@@ -0,0 +1,20 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Is a resolved module export something React can render?
+ *
+ * `typeof x === "function"` is NOT that question. memo(), forwardRef() and
+ * lazy() all return OBJECTS carrying a `$$typeof` symbol, so a shape check on
+ * `function` rejects three of React's own idioms as "not a component".
+ * Measured 2026-09-01: scala-projects skipped PresenceAvatars for exactly this
+ * reason — the block is `memo(function PresenceAvatarsBlock(...))` — and every
+ * page rendering it came out blank with no error beyond one boot WARN.
+ */
+
+export function isReactElementType(value: unknown): boolean {
+	if (typeof value === "function") return true;
+	if (typeof value !== "object" || value === null) return false;
+	return typeof (value as { $$typeof?: unknown }).$$typeof === "symbol";
+}