@teamscala/service-boot 0.23.442 → 0.23.444

package/package.json

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

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

@@ -0,0 +1,93 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * verifyClientBuildAssets is 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 assets it names exist on disk. Measured 2026-09-01
+ * (the unstyled-proposal incident): a manifest that never ran — or a first-boot
+ * tombstone carrying the unhashed FALLBACK_MANIFEST paths — read as a
+ * legitimate bundle and the service served pages whose stylesheet 404'd while
+ * every health surface reported ok. These tests pin the refusal for all three
+ * unbuilt shapes and the pass for a real build.
+ */
+
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeManifest, verifyClientBuildAssets } from "./manifest.ts";
+
+let dir: string;
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), "verify-client-build-"));
+	await mkdir(join(dir, "dist", "client"), { recursive: true });
+});
+
+afterEach(async () => {
+	await rm(dir, { recursive: true, force: true });
+});
+
+async function writeAssetFiles(styles: string, hydrate: string): Promise<void> {
+	await Bun.file(join(dir, "dist", "client", styles.replace(/^\/assets\//, ""))).write("body{}");
+	await Bun.file(join(dir, "dist", "client", hydrate.replace(/^\/assets\//, ""))).write("export{}");
+}
+
+describe("verifyClientBuildAssets", () => {
+	test("a manifest whose files both exist verifies", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles-abc.css",
+			hydratePath: "/assets/hydrate-abc.js",
+		});
+		await writeAssetFiles("/assets/styles-abc.css", "/assets/hydrate-abc.js");
+		expect(await verifyClientBuildAssets(dir)).toEqual({ ok: true });
+	});
+
+	test("an absent manifest refuses — the client build never ran", async () => {
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("never ran or its output is gone");
+	});
+
+	test("the first-boot tombstone shape (unhashed paths, no files) refuses", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles.css",
+			hydratePath: "/assets/hydrate.js",
+		});
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("unbuilt assets");
+	});
+
+	test("a path-less tombstone (the shape build-client-assets now writes) refuses as unbuilt", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			inputFingerprint: "failed:2026-09-01T00:00:00.000Z",
+			buildFailed: true,
+			buildFailedReason: "hydrate build failed: something",
+			buildFailedAt: "2026-09-01T00:00:00.000Z",
+		} as never);
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("never ran or its output is gone");
+	});
+
+	test("a manifest naming a file that was deleted refuses (stale-bundle shape)", async () => {
+		await writeManifest(join(dir, "dist", "client"), {
+			stylesPath: "/assets/styles-abc.css",
+			hydratePath: "/assets/hydrate-abc.js",
+		});
+		await writeAssetFiles("/assets/styles-abc.css", "/assets/hydrate-abc.js");
+		await rm(join(dir, "dist", "client", "hydrate-abc.js"));
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+		if (!result.ok) expect(result.reason).toContain("hydrate bundle");
+	});
+
+	test("an unreadable manifest refuses", async () => {
+		await Bun.file(join(dir, "dist", "client", "asset-manifest.json")).write("{broken");
+		const result = await verifyClientBuildAssets(dir);
+		expect(result.ok).toBe(false);
+	});
+});

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

@@ -21,8 +21,13 @@ import type { SourceMapUploadResult } from "./sourcemaps-upload.ts";
 export const MANIFEST_FILE = "asset-manifest.json";
 
 export interface AssetManifest {
-	stylesPath: string;
-	hydratePath: string;
+	// Optional because a TOMBSTONE from a build that failed with no prior
+	// success carries NO paths — there are no real assets to name, and inventing
+	// URLs nothing built is the deleted fallback class (no-shims).
+	// `readManifest` returns null unless both are present, so a path-less
+	// tombstone reads as unbuilt everywhere (verification, readiness, render).
+	stylesPath?: string;
+	hydratePath?: string;
 	// Content fingerprint of the CLIENT-BUNDLE DEPENDENCY CLOSURE (source entrypoints + @teamscala/* JS/CSS in the closure + third-party closure-dep
 	// versions), hashed by CONTENT — never mtime (cache-key-hashes-source- inputs-only). The boot/build freshness check rebuilds iff this differs
 	// from the current closure. mtime comparison is fundamentally broken on Railway: deploy-build bakes the bundle at image-build time, and under the
@@ -53,15 +58,6 @@ export interface AssetManifest {
 	sourceMaps?: SourceMapUploadResult;
 }
 
-// Last-resort paths for a tombstone when no prior successful manifest exists
-// (first-ever boot fails). Points at the unhashed build names so an operator
-// inspecting the manifest sees a real (if 404-ing) target rather than a
-// mystery sentinel.
-export const FALLBACK_MANIFEST: { stylesPath: string; hydratePath: string } = {
-	stylesPath: "/assets/styles.css",
-	hydratePath: "/assets/hydrate.js",
-};
-
 /**
  * Read ONLY the tombstone state of the current manifest — the runtime
  * (read-html-template, ui-service) calls this to decide whether to surface a
@@ -125,10 +121,9 @@ export async function writeManifest(
  * 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:
+ * exist on disk. An absent or unreadable manifest, a first-boot tombstone
+ * carrying no paths, and any manifest naming files that do not exist must all
+ * 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.
@@ -138,7 +133,7 @@ export async function verifyClientBuildAssets(
 ): Promise<{ ok: true } | { ok: false; reason: string }> {
 	const outDir = join(cwd, "dist", "client");
 	const manifest = await readManifest(outDir);
-	if (!manifest) {
+	if (!manifest || !manifest.stylesPath || !manifest.hydratePath) {
 		return {
 			ok: false,
 			reason: `no readable asset manifest at ${join(outDir, MANIFEST_FILE)} — the client build never ran or its output is gone`,

package/src/build-client-assets.ts

@@ -60,7 +60,6 @@ import { CLIENT_BUILD_LOCK, getClientBuildLockTimeoutMs } from "./build-client-a
 import { buildHydrateBundle } from "./build-client-assets/hydrate-bundle.ts";
 import { computeInputFingerprint } from "./build-client-assets/input-fingerprint.ts";
 import {
-	FALLBACK_MANIFEST,
 	readManifest,
 	writeManifest,
 } from "./build-client-assets/manifest.ts";
@@ -85,7 +84,9 @@ export async function buildClientAssets(serviceSlug: string): Promise<void> {
 		// 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);
+		const release = existingManifest.hydratePath
+			? releaseFromHydratePath(existingManifest.hydratePath)
+			: null;
 		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}`,
@@ -143,10 +144,19 @@ async function performBuild(
 		try {
 			await mkdir(outDir, { recursive: true });
 			await writeManifest(outDir, {
-				// Preserve last-good paths so SSR serves the prior bundle
-				// rather than a 404 hydrate — degraded but not dead.
-				stylesPath: existingManifest?.stylesPath ?? FALLBACK_MANIFEST.stylesPath,
-				hydratePath: existingManifest?.hydratePath ?? FALLBACK_MANIFEST.hydratePath,
+				// NO invented paths: when a prior successful build exists its real
+				// paths are preserved (SSR keeps serving the prior bundle — degraded
+				// but coherent); when none exists the tombstone carries NO asset
+				// paths at all. Writing the unhashed build names here was the last
+				// remnant of the deleted fallback class — paths that name files
+				// nothing built must not exist on disk any more than in served HTML.
+				// A path-less tombstone reads as unbuilt everywhere (readManifest →
+				// null → verification refuses → readiness never flips), and its
+				// buildFailedReason below is the operator's diagnostic — the failure
+				// is read via readClientBuildStatus, which never needed the paths.
+				...(existingManifest?.stylesPath && existingManifest?.hydratePath
+					? { stylesPath: existingManifest.stylesPath, hydratePath: existingManifest.hydratePath }
+					: {}),
 				// Failure sentinel: the next boot's fingerprint check reads
 				// this and cannot match any real fingerprint → forces a retry.
 				inputFingerprint: `failed:${new Date().toISOString()}`,

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

@@ -68,29 +68,35 @@ describe("readHtmlTemplate manifest-keyed cache", () => {
 		expect(second).not.toContain("/assets/hydrate-old.js");
 	});
 
-	test("falls back to fixed paths when the manifest is absent", async () => {
-		const html = await readHtmlTemplate();
-		expect(html).toContain("/assets/hydrate.js");
-		expect(html).toContain("/assets/styles.css");
+	// The fallback is DELETED: the unhashed names it emitted were never built,
+	// so the page 200'd while its stylesheet 404'd. Measured 2026-09-01 — a
+	// client-facing proposal served unstyled while the deploy reported SUCCESS.
+	// A manifest-less render must THROW into the branded error-page path, never
+	// emit HTML; the readiness gate (verifyClientBuildAssets) holds the service
+	// unready, and this throw covers a manifest that vanishes after boot.
+	test("refuses to render when the manifest is absent — never emits fallback URLs", async () => {
+		expect(readHtmlTemplate()).rejects.toThrow("no servable asset manifest");
 	});
 
-	// 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("refuses to render when the manifest is unreadable garbage", async () => {
+		await Bun.file(join(dir, "dist", "client", "asset-manifest.json")).write("{not json");
+		expect(readHtmlTemplate()).rejects.toThrow("no servable asset manifest");
+	});
+
+	test("the refusal names the manifest path, so the fix is one read away", async () => {
+		const path = join(dir, "dist", "client", "asset-manifest.json");
+		try {
+			await readHtmlTemplate();
+			throw new Error("expected readHtmlTemplate to throw");
+		} catch (error) {
+			expect((error as Error).message).toContain(path);
+		}
 	});
 
-	test("does not stamp missing-manifest once a real manifest exists", async () => {
+	test("does not stamp anything 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"');
+		expect(html).not.toContain("x-client-build-status");
 	});
 });

package/src/read-html-template.ts

@@ -29,6 +29,18 @@
  * Re-stat'ing the tiny manifest per request is negligible (OS-cached, no
  * network); the substituted HTML is reused while the mtime is unchanged.
  *
+ * NO SERVED HTML WITHOUT A VERIFIED MANIFEST: when the manifest is absent,
+ * unreadable, or names files that do not exist, this module THROWS rather
+ * than emitting HTML — the fixed-name fallback (`/assets/styles.css`,
+ * `/assets/hydrate.js`) it once served names files NOTHING builds, so a
+ * 200 page with those URLs was a stylesheet 404 wearing a working page's
+ * clothes. Measured 2026-09-01: proposals.scala.business served a
+ * client-facing proposal unstyled while Railway reported the deploy
+ * SUCCESS. The readiness flip now gates on `verifyClientBuildAssets`
+ * (build-client-assets/manifest.ts), so this throw is defence in depth for
+ * a manifest that vanishes mid-process; the page-server render catch turns
+ * it into the branded error page, never a 200 with dead URLs.
+ *
  * NO-SILENT-REVERTS: when the manifest is a TOMBSTONE (the last client build
  * failed), the served HTML is stamped with a `<meta name="x-client-build-status"
  * content="failed">` tag in <head> so any operator / chrome-devtools / theme
@@ -40,7 +52,6 @@
  */
 
 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";
 
@@ -49,11 +60,6 @@ interface AssetManifest {
 	hydratePath: string;
 }
 
-const FALLBACK: AssetManifest = {
-	stylesPath: "/assets/styles.css",
-	hydratePath: "/assets/hydrate.js",
-};
-
 const PAGE_DOCUMENT = `<!doctype html>
 <html lang="en">
 	<head>
@@ -95,54 +101,46 @@ async function manifestMtimeMs(): Promise<number> {
 }
 
 async function loadManifest(): Promise<AssetManifest | null> {
+	// Pure read: this function must NOT throw on a missing or unreadable
+	// manifest, and must NOT depend on the app logger (other suites mock it
+	// with a partial shape). The gate's `boot.client-build-failed` event is
+	// the single home for the diagnostic — adding a warn here duplicates it
+	// and risks a missing method on a mocked logger.
 	const path = manifestPath();
-	if (await Bun.file(path).exists()) {
-		try {
-			const parsed = await Bun.file(path).json() as Partial<AssetManifest>;
-			if (parsed.stylesPath && parsed.hydratePath) {
-				return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
-			}
-			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,
-			);
+	if (!(await Bun.file(path).exists())) return null;
+	try {
+		const parsed = (await Bun.file(path).json()) as Partial<AssetManifest>;
+		if (parsed.stylesPath && parsed.hydratePath) {
+			return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 		}
-		return null;
+	} catch {
+		// fall through to null — gate + boot log will name the reason.
 	}
-	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;
 }
 
+function manifestCacheKey(): string {
+	// Keying by the manifest path means two testdirs (or two concurrent
+	// services in one process, e.g. a fleet supervisor probe) cannot poison
+	// each other's cache — absent and present manifests carry different paths.
+	return manifestPath();
+}
+
 export async function readHtmlTemplate(): Promise<string> {
 	const manifestMtime = await manifestMtimeMs();
-	const cached = htmlCache.get("default");
+	const cached = htmlCache.get(manifestCacheKey());
 	if (cached && cached.manifestMtime === manifestMtime) return cached.html;
 	const manifest = await loadManifest();
-	let html = PAGE_DOCUMENT
-		.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}`;
+		throw new Error(
+			`[read-html-template] no servable asset manifest (${manifestPath()}) — refusing to emit HTML referencing unbuilt asset URLs. ` +
+				`The readiness gate (verifyClientBuildAssets) should have held this service unready; a manifest disappearing after boot is the remaining path. ` +
+				`Fix the client build and restart.`,
+		);
 	}
+	let html = PAGE_DOCUMENT
+		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
+		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath);
 	// 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
@@ -155,6 +153,6 @@ export async function readHtmlTemplate(): Promise<string> {
 			? html.replace("</head>", `${meta}</head>`)
 			: `${meta}${html}`;
 	}
-	htmlCache.set("default", { html, manifestMtime });
+	htmlCache.set(manifestCacheKey(), { html, manifestMtime });
 	return html;
 }

package/src/two-phase-full-app.test.ts

@@ -79,4 +79,39 @@ describe("phase-2 step isolation", () => {
 		// original invisibility from the other direction.
 		expect(body.slice(guardCatch, guardCatch + 400)).toContain("log.error");
 	});
+
+	/*
+	 * THE 2026-09-01 REGRESSION (the unstyled-proposal incident). The phase-1
+	 * catch made the build failure non-fatal, and the readiness flip
+	 * (setPageHandler / markFullAppReady) ran unconditionally afterwards — so a
+	 * deployment whose client build never ran flipped ready, served pages, and
+	 * answered /health 200 while every asset URL 404'd. Railway reported the
+	 * deploy SUCCESS. The flip must be gated on a VERIFIED manifest, and the
+	 * gate must sit AFTER mountPgBoss so background work still mounts (the
+	 * isolation above), and BEFORE both flip call sites.
+	 */
+	test("readiness flips only after the client build verifies, and the gate sits after the jobs", () => {
+		const body = buildFullAppBody();
+		const boss = body.indexOf("mountPgBoss(");
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const flipBlock = body.indexOf("if (deps.createPageHandler)");
+		expect(boss).toBeGreaterThan(-1);
+		expect(gate).toBeGreaterThan(boss);
+		expect(flipBlock).toBeGreaterThan(gate);
+
+		// BOTH flip call sites are after the gate: the SSR path
+		// (setPageHandler) and the client-only path (markFullAppReady).
+		const setPageHandlerCall = body.indexOf("setPageHandler(deps.createPageHandler)");
+		const markFullAppReadyCall = body.indexOf("markFullAppReady()");
+		expect(setPageHandlerCall).toBeGreaterThan(gate);
+		expect(markFullAppReadyCall).toBeGreaterThan(gate);
+	});
+
+	test("a failed verification throws — the boot never continues past an unverified manifest", () => {
+		const body = buildFullAppBody();
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const slice = body.slice(gate, gate + 1200);
+		expect(slice).toContain("!clientBuild.ok");
+		expect(slice).toContain("throw new Error");
+	});
 });

package/src/two-phase-full-app.ts

@@ -59,6 +59,7 @@
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { buildClientAssets } from "./build-client-assets.ts";
+import { verifyClientBuildAssets } from "./build-client-assets/manifest.ts";
 import { mountPgBoss } from "./pg-boss-mount.ts";
 import { swapApp } from "./mutable-app-ref.ts";
 import type { MinimalAppResult } from "./two-phase-minimal-app.ts";
@@ -112,6 +113,33 @@ export async function buildFullApp(
 		);
 	}
 
+	// The readiness flip is gated on a VERIFIED client build, never on "phase 2
+	// got this far". buildClientAssets's failure above is deliberately non-fatal
+	// for background work — but a deployment whose client build never ran (or
+	// whose tombstone names unbuilt files) must not flip ready and serve pages:
+	// every served asset URL would 404 while /health and the deploy report ok.
+	// Measured 2026-09-01: proposals.scala.business served a client-facing
+	// proposal unstyled while Railway reported SUCCESS, because the phase-1
+	// catch let boot continue past the build and the flip never checked the
+	// build's outcome (`a-component-may-not-report-a-state-it-has-not-verified`).
+	// The throw lands in ui-service's boot.client-build-failed catch, which
+	// keeps the minimal app: pages and /health stay 503 (cleanly unavailable)
+	// while the pg-boss jobs mounted above KEEP RUNNING. On Railway the
+	// healthcheck (healthcheckPath: /health) then fails and the previous good
+	// deployment keeps traffic — the deploy reports FAILED, never SUCCESS.
+	// readiness-gated-boot: a service is "fully-ready or cleanly-unavailable";
+	// a UI service that cannot serve its bundle is not ready
+	// (`liveness-by-capability-not-process-existence`).
+	const clientBuild = await verifyClientBuildAssets();
+	if (!clientBuild.ok) {
+		throw new Error(
+			`[two-phase-boot:${serviceSlug}] refusing readiness — ${clientBuild.reason}. ` +
+				`Serving pages here would emit asset URLs that 404 while every health surface reports ok. ` +
+				`Background work is mounted and unaffected; pages and /health stay unavailable until a real client build exists. ` +
+				`Fix the client build (see build-client-assets logs above) and restart.`,
+		);
+	}
+
 	log.info(
 		`[two-phase-boot:${serviceSlug}] Full app built: ${loaded.length} block(s), ` +
 			`${Object.keys(components).length} component(s)`,