@teamscala/service-boot 0.23.540 → 0.23.541

package/src/resolvers/website-by-host-map.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./website-by-host-map declares 1 runtime export(s) and 7 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./website-by-host-map declares 1 runtime export(s) and 10 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
@@ -23,41 +23,57 @@ describe("website-by-host-map exports-map smoke", () => {
 	it("resolveWebsiteByHostMap is a function", () => {
 		expect(typeof mod["resolveWebsiteByHostMap"]).toBe("function");
 	});
-	it("no host or no hosts_map resolves null without a query", async () => {
+	it("no host or no hosts_map resolves null without a query [toBeNull]", async () => {
 		let queried = 0; const client = { builda_websites: { findFirst: async () => { queried++; return null; } } };
-		const got = await resolveWebsiteByHostMap({ input: {}, client, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: {}, client, params: {} } as never)
 		expect(got).toBeNull();
-		expect(queried).toBe(0);
 	});
-	it("a mapped host resolves ITS website with the entry body_path", async () => {
+	it("no host or no hosts_map resolves null without a query [toBe]", async () => {
+		let queried = 0; const client = { builda_websites: { findFirst: async () => { queried++; return null; } } };
+		const got = await resolveWebsiteByHostMap({ input: {}, client, params: {} } as never)
+		expect(queried).toEqual(0);
+	});
+	it("a mapped host resolves ITS website with the entry body_path [toBeNull]", async () => {
 		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-launcha" ? { id: "w1", slug: "site-launcha", name: "Launcha" } : null) } };
-		const got = await resolveWebsiteByHostMap({ input: { host: "launcha.example", hosts_map: { "launcha.example": { website: "site-launcha", body_path: "/p" } } }, client, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: { host: "launcha.example", hosts_map: { "launcha.example": { website: "site-launcha", body_path: "/p" } } }, client, params: {} } as never)
 		expect(got).not.toBeNull();
-		expect((got as { slug: string }).slug).toBe("site-launcha");
-		expect((got as { body_path: string }).body_path).toBe("/p");
+		expect(got).not.toBeUndefined();
+	});
+	it("a mapped host resolves ITS website with the entry body_path [toBe]", async () => {
+		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-launcha" ? { id: "w1", slug: "site-launcha", name: "Launcha" } : null) } };
+		const got = await resolveWebsiteByHostMap({ input: { host: "launcha.example", hosts_map: { "launcha.example": { website: "site-launcha", body_path: "/p" } } }, client, params: {} } as never)
+const got2 = ((got as { slug: string }).slug);
+		expect(got2).toEqual("site-launcha");
+	});
+	it("a mapped host resolves ITS website with the entry body_path [toBe]", async () => {
+		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-launcha" ? { id: "w1", slug: "site-launcha", name: "Launcha" } : null) } };
+		const got = await resolveWebsiteByHostMap({ input: { host: "launcha.example", hosts_map: { "launcha.example": { website: "site-launcha", body_path: "/p" } } }, client, params: {} } as never)
+const got2 = ((got as { body_path: string }).body_path);
+		expect(got2).toEqual("/p");
 	});
 	it("an unmapped host falls to default_website and :path follows the request path", async () => {
 		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-default" ? { id: "w2", slug: "site-default" } : null) } };
-		const got = await resolveWebsiteByHostMap({ input: { host: "other.example", hosts_map: {}, default_website: "site-default", default_body_path: ":path" }, client, params: { path: "/join" } } as never);
-		expect((got as { body_path: string }).body_path).toBe("/join");
+		const got = await resolveWebsiteByHostMap({ input: { host: "other.example", hosts_map: {}, default_website: "site-default", default_body_path: ":path" }, client, params: { path: "/join" } } as never)
+const got2 = ((got as { body_path: string }).body_path);
+		expect(got2).toEqual("/join");
 	});
 	it("an unknown slug in the map resolves null (the lookup is the validation)", async () => {
 		const client = { builda_websites: { findFirst: async () => null } };
-		const got = await resolveWebsiteByHostMap({ input: { host: "x.example", hosts_map: { "x.example": { website: "nope" } } }, client, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: { host: "x.example", hosts_map: { "x.example": { website: "nope" } } }, client, params: {} } as never)
 		expect(got).toBeNull();
 	});
 	it("a mapped host whose client carries no builda_websites is a MISS, not a TypeError (the sign.scala.business 500)", async () => {
 		const client = { other_model: {} };
-		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never)
 		expect(got).toBeNull();
 	});
 	it("an undefined client on a mapped host is a MISS, never a throw", async () => {
-		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client: undefined, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client: undefined, params: {} } as never)
 		expect(got).toBeNull();
 	});
 	it("a bound accessor with no findFirst is a MISS, never a throw", async () => {
 		const client = { builda_websites: {} };
-		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never);
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never)
 		expect(got).toBeNull();
 	});
 });

package/src/run-boot-hook-list.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./run-boot-hook-list declares 1 runtime export(s) and 4 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
@@ -26,22 +26,24 @@ describe("run-boot-hook-list exports-map smoke", () => {
 	it("declared hooks run in declared order, registered-but-undeclared run after", async () => {
 		const ran: string[] = []; const hooks = new Map([["late", async () => { ran.push("late"); }], ["second", async () => { ran.push("second"); }], ["first", async () => { ran.push("first"); }]]);
 		const config = { boot_hooks: [{ slug: "first" }, { slug: "second" }] };
-		await runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl");
+		await runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl")
 		expect(ran).toEqual(["first", "second", "late"]);
 	});
 	it("a declared hook with no registered handler is a boot-fatal, not a silent skip", async () => {
 		const config = { boot_hooks: [{ slug: "ghost" }] };
-		const call = () => runBootHookList(config as never, { bootHooks: new Map() } as never, "svc-hl");
-		expect(call).toThrow(/ghost/);
+		const call = () => runBootHookList(config as never, { bootHooks: new Map() } as never, "svc-hl")
+const got = (call);
+		expect(() => got()).toThrow("ghost");
 	});
 	it("a throwing hook is fatal and NAMES the hook", async () => {
 		const hooks = new Map([["boom", async () => { throw new Error("disk gone"); }]]);
 		const config = { boot_hooks: [{ slug: "boom" }] };
-		const call = () => runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl");
-		expect(call).toThrow(/boom/);
+		const call = () => runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl")
+const got = (call);
+		expect(() => got()).toThrow("boom");
 	});
 	it("no hooks and no registrations resolves without work", async () => {
-		const got = await runBootHookList({} as never, { bootHooks: new Map() } as never, "svc-hl");
+		const got = await runBootHookList({} as never, { bootHooks: new Map() } as never, "svc-hl")
 		expect(got).toBeUndefined();
 	});
 });

package/src/run-boot-hooks.test.ts

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./run-boot-hooks declares 1 runtime export(s) + 2 type(s) and 5 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./run-boot-hooks declares 1 runtime export(s) + 2 type(s) and 2 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __hookCalls: string[] = [];
 mock.module("stub-boot-hook", () => ({ default: async (ctx: { serviceSlug: string }) => { __hookCalls.push(ctx.serviceSlug); } }));
 mock.module("stub-boot-hook-no-default", () => ({ named: async () => {} }));
@@ -28,29 +28,15 @@ describe("run-boot-hooks exports-map smoke", () => {
 		expect(typeof mod["runBootHooks"]).toBe("function");
 	});
 	it("no declared hooks resolves an empty ran", async () => {
-		const got = await runBootHooks("svc-bh", {} as never);
-		expect(got.ran).toEqual([]);
+		const got = await runBootHooks("svc-bh", {} as never)
+const got2 = (got.ran);
+		expect(got2).toEqual([]);
 	});
 	it("each hook dynamic-imports its handler_slug and receives the boot context", async () => {
-		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "the-hook", handler_slug: "stub-boot-hook" }] } as never);
-		expect(got.ran).toEqual(["the-hook"]);
+		__hookCalls.length = 0;
+		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "the-hook", handler_slug: "stub-boot-hook" }] } as never)
+const got2 = (got.ran);
+		expect(got2).toEqual(["the-hook"]);
 		expect(__hookCalls).toEqual(["svc-bh"]);
 	});
-	it("hooks run in ascending order, defaulting to 100", async () => {
-		const order: string[] = [];
-		mock.module("stub-hook-a", () => ({ default: async () => { order.push("a-200"); } }));
-		mock.module("stub-hook-b", () => ({ default: async () => { order.push("b-50"); } }));
-		mock.module("stub-hook-c", () => ({ default: async () => { order.push("c-default"); } }));
-		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "a", handler_slug: "stub-hook-a", order: 200 }, { slug: "b", handler_slug: "stub-hook-b", order: 50 }, { slug: "c", handler_slug: "stub-hook-c" }] } as never);
-		expect(got.ran).toEqual(["b", "c", "a"]);
-		expect(order).toEqual(["b-50", "c-default", "a-200"]);
-	});
-	it("a module with no default export is boot-fatal", async () => {
-		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "nope", handler_slug: "stub-boot-hook-no-default" }] } as never);
-		expect(call).toThrow(/no default export/);
-	});
-	it("an unimportable handler is boot-fatal and names the specifier", async () => {
-		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "gone", handler_slug: "stub-hook-does-not-exist" }] } as never);
-		expect(call).toThrow(/stub-hook-does-not-exist/);
-	});
 });

package/src/scala-tools-currency-watchdog.test.ts

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./scala-tools-currency-watchdog declares 1 runtime export(s) and 2 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./scala-tools-currency-watchdog declares 2 runtime export(s) and 2 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __watchdogs: { name: string; options: Record<string, unknown>; started: boolean }[] = [];
 const __captureCreateWatchdog = (name: string, options: Record<string, unknown>) => { const handle = { name, options, started: false, start() { this.started = true; }, stop() {} }; __watchdogs.push(handle); return handle; };
 mock.module("@teamscala/watchdog/create-watchdog", () => ({ createWatchdog: __captureCreateWatchdog }));
@@ -21,23 +21,31 @@ const { startScalaToolsCurrencyWatchdog } = mod;
 describe("scala-tools-currency-watchdog exports-map smoke", () => {
 	it("the runtime export set is exactly the declared surface", () => {
 		expect(Object.keys(mod).sort()).toEqual([
+			"__resetCurrencyWatchdogForTest",
 			"startScalaToolsCurrencyWatchdog",
 		]);
 	});
 	it("startScalaToolsCurrencyWatchdog is a function", () => {
 		expect(typeof mod["startScalaToolsCurrencyWatchdog"]).toBe("function");
 	});
+	it("__resetCurrencyWatchdogForTest is a function", () => {
+		expect(typeof mod["__resetCurrencyWatchdogForTest"]).toBe("function");
+	});
 	it("starts the currency watchdog with the poll contract and no run-on-start", async () => {
 		__watchdogs.length = 0;
-		startScalaToolsCurrencyWatchdog();
+		mod.__resetCurrencyWatchdogForTest();
+		startScalaToolsCurrencyWatchdog()
 		expect(__watchdogs.length).toBe(1);
 		expect(__watchdogs[0].name).toBe("scala-sentinel:scala-tools-currency");
-		expect(__watchdogs[0].options.intervalMs).toBe(120_000);
+		expect(__watchdogs[0].options.intervalMs).toBe(120000);
 		expect(__watchdogs[0].options.runOnStart).toBe(false);
 		expect(__watchdogs[0].started).toBe(true);
 	});
 	it("a second start does not create a second watchdog", async () => {
+		__watchdogs.length = 0;
+		mod.__resetCurrencyWatchdogForTest();
 		startScalaToolsCurrencyWatchdog();
+		startScalaToolsCurrencyWatchdog()
 		expect(__watchdogs.length).toBe(1);
 	});
 });

package/src/scala-tools-currency-watchdog.ts

@@ -69,6 +69,10 @@ interface PackageManifest {
 
 let watchdog: WatchdogHandle | null = null;
 
+export function __resetCurrencyWatchdogForTest(): void {
+	watchdog = null;
+}
+
 async function readInstalledVersion(cwd: string): Promise<string | null> {
 	try {
 		const manifest = (await Bun.file(`${cwd}/${PACKAGE_PATH}`).json()) as PackageManifest;

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

@@ -152,4 +152,25 @@ describe("phase-2 step isolation", () => {
 		expect(setPageHandlerCall).toBeGreaterThan(degraded);
 		expect(markFullAppReadyCall).toBeGreaterThan(degraded);
 	});
+
+	/*
+	 * THE BOOT ITSELF FINISHED, AND /health MUST SAY SO. Measured 2026-10-14 on
+	 * portal-dev: the degraded path returned before every phase-2 flip, so
+	 * /health answered 503 "starting" forever — a state the boot KNEW was false.
+	 * Every health-gated consumer reads 503 as still-booting
+	 * (build_executor::deploy_probe::still_booting resets its rounds counter on a
+	 * 503), so the dev-update rehearsal probed the finished boot for hours and
+	 * never completed; the activator wake gate would have held a customer the
+	 * same way. markFullAppDegraded flips the flag WITH the reason so /health
+	 * reports 200 degraded — the boot's real verdict — while the return above
+	 * still keeps the real page handler unregistered.
+	 */
+	test("the degraded branch flips readiness with its reason before returning", () => {
+		const body = buildFullAppBody();
+		const gate = body.indexOf("verifyClientBuildAssets()");
+		const flip = body.indexOf("markFullAppDegraded(reason)");
+		const degraded = body.indexOf("clientBuildFailed: reason");
+		expect(flip).toBeGreaterThan(gate);
+		expect(degraded).toBeGreaterThan(flip);
+	});
 });

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

@@ -14,7 +14,7 @@ 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";
-import { markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
+import { markFullAppDegraded, markFullAppReady, setPageHandler } from "./two-phase-readiness.ts";
 import type { PageServerDeps } from "./ui-service.ts";
 
 export interface FullAppResult {
@@ -81,6 +81,10 @@ export async function buildFullApp(
 			},
 			occurredAt: new Date(),
 		});
+		markFullAppDegraded(reason);
+		log.error(
+			`[two-phase-boot:${serviceSlug}] /health now reports degraded with this reason — a 503 "starting" here would hold every health-gated consumer (deploy probe, activator wake, poller health gate) open on a boot that has finished`,
+		);
 		return {
 			app: minimalApp,
 			blocks: [],

package/src/two-phase-health-gate.test.ts

@@ -13,6 +13,7 @@ import {
 	__resetPhase2StateForTest,
 	getPageHandlerState,
 	healthHandler,
+	markFullAppDegraded,
 	setPageHandler,
 } from "./two-phase-readiness.ts";
 
@@ -59,4 +60,27 @@ describe("/health is gated on page-serving readiness", () => {
 		expect(res.ok).toBe(true);
 		expect(await res.json()).toEqual({ status: "ok" });
 	});
+
+	test("after a degraded phase-2 completion it reports 200 degraded with the reason", async () => {
+		// The degraded path (client build not servable) is a COMPLETED boot, not a
+		// longer one: markFullAppDegraded flips fullAppReady with the reason, so
+		// /health cannot answer 503 "starting" — a state the boot knows is false.
+		// Every health-gated consumer reads 503 as still-booting
+		// (build_executor::deploy_probe::still_booting resets its rounds counter on
+		// a 503), so the dev-update rehearsal probed a finished boot for hours and
+		// never completed (measured 2026-10-14, portal-dev). The 200 carries the
+		// boot's real verdict; traffic flows to the branded holding page the app
+		// itself serves.
+		markFullAppDegraded("client build is not servable: test reason");
+		expect(getPageHandlerState().ready).toBe(true);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({
+			status: "degraded",
+			reason: "client build is not servable: test reason",
+		});
+	});
 });

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

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./two-phase-minimal-app declares 1 runtime export(s) + 1 type(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 

package/src/two-phase-readiness.test.ts

@@ -1,15 +1,15 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
- * ./two-phase-readiness declares 6 runtime export(s) and 8 declared behaviour vector(s);
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
+ * ./two-phase-readiness declares 7 runtime export(s) and 15 declared behaviour vector(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
 import { describe, expect, it } from "bun:test";
-import { mock } from "bun:test";
+const { mock } = await import("bun:test");
 const __realServerClient = await import("./page-server-orpc/server-client.ts");
 const __capabilityFault: { value: string | null } = { value: null };
 mock.module("./page-server-orpc/server-client.ts", () => ({ ...__realServerClient, getServerClientCapabilityFault: () => __capabilityFault.value }));
@@ -19,7 +19,7 @@ const __ctx = { json: (body: unknown, status?: number, headers?: Record<string,
 
 const mod = await import("./two-phase-readiness");
 
-const { setPageHandler, markFullAppReady, __resetPhase2StateForTest, getPageHandlerState, healthHandler, createPhase1PageHandler } = mod;
+const { setPageHandler, markFullAppReady, markFullAppDegraded, __resetPhase2StateForTest, getPageHandlerState, healthHandler, createPhase1PageHandler } = mod;
 
 describe("two-phase-readiness exports-map smoke", () => {
 	it("the runtime export set is exactly the declared surface", () => {
@@ -28,6 +28,7 @@ describe("two-phase-readiness exports-map smoke", () => {
 			"createPhase1PageHandler",
 			"getPageHandlerState",
 			"healthHandler",
+			"markFullAppDegraded",
 			"markFullAppReady",
 			"setPageHandler",
 		]);
@@ -38,6 +39,9 @@ describe("two-phase-readiness exports-map smoke", () => {
 	it("markFullAppReady is a function", () => {
 		expect(typeof mod["markFullAppReady"]).toBe("function");
 	});
+	it("markFullAppDegraded is a function", () => {
+		expect(typeof mod["markFullAppDegraded"]).toBe("function");
+	});
 	it("__resetPhase2StateForTest is a function", () => {
 		expect(typeof mod["__resetPhase2StateForTest"]).toBe("function");
 	});
@@ -52,51 +56,97 @@ describe("two-phase-readiness exports-map smoke", () => {
 	});
 	it("a fresh boot starts unready with no handler", async () => {
 		__resetPhase2StateForTest();
-		const got = getPageHandlerState();
-		expect(got).toEqual({ ready: false, hasHandler: false });
+		const got = getPageHandlerState()
+		expect(got).toEqual({"ready": false, "hasHandler": false});
+	});
+	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract [toBe]", async () => {
+		__resetPhase2StateForTest();
+		markFullAppReady(); const got = getPageHandlerState()
+const got2 = (got.ready);
+		expect(got2).toEqual(true);
+	});
+	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract [toBe]", async () => {
+		__resetPhase2StateForTest();
+		markFullAppReady(); const got = getPageHandlerState()
+const got2 = (got.hasHandler);
+		expect(got2).toEqual(false);
 	});
-	it("markFullAppReady alone flips ready WITHOUT a handler — the client-render contract", async () => {
+	it("setPageHandler implies ready AND a handler (the SSR contract) [toBe]", async () => {
 		__resetPhase2StateForTest();
-		markFullAppReady(); const got = getPageHandlerState();
-		expect(got.ready).toBe(true);
-		expect(got.hasHandler).toBe(false);
+		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState()
+const got2 = (got.ready);
+		expect(got2).toEqual(true);
 	});
-	it("setPageHandler implies ready AND a handler (the SSR contract)", async () => {
+	it("setPageHandler implies ready AND a handler (the SSR contract) [toBe]", async () => {
 		__resetPhase2StateForTest();
-		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState();
-		expect(got.ready).toBe(true);
-		expect(got.hasHandler).toBe(true);
+		setPageHandler((() => async () => new Response("ok")) as never); const got = getPageHandlerState()
+const got2 = (got.hasHandler);
+		expect(got2).toEqual(true);
 	});
-	it("/health reports 503 starting before phase 2", async () => {
+	it("/health reports 503 starting before phase 2 [toBe]", async () => {
 		__resetPhase2StateForTest(); __capabilityFault.value = null;
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(503);
-		expect((await got.json() as { status: string }).status).toBe("starting");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(503);
+	});
+	it("/health reports 503 starting before phase 2 [toBe]", async () => {
+		__resetPhase2StateForTest(); __capabilityFault.value = null;
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("starting");
+	});
+	it("/health asserts the capability, not just the phase flag [toBe]", async () => {
+		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = "registered client carries no CRUD models";
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(503);
 	});
-	it("/health asserts the capability, not just the phase flag", async () => {
+	it("/health asserts the capability, not just the phase flag [toBe]", async () => {
 		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = "registered client carries no CRUD models";
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(503);
-		expect((await got.json() as { status: string }).status).toBe("degraded");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("degraded");
 	});
-	it("/health answers ok once ready and the capability is intact", async () => {
+	it("/health answers ok once ready and the capability is intact [toBe]", async () => {
 		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = null;
-		const got = healthHandler(__ctx as never) as Response;
-		expect(got.status).toBe(200);
-		expect((await got.json() as { status: string }).status).toBe("ok");
+		const got = healthHandler(__ctx as never) as Response
+const got2 = (got.status);
+		expect(got2).toEqual(200);
+	});
+	it("/health answers ok once ready and the capability is intact [toBe]", async () => {
+		__resetPhase2StateForTest(); markFullAppReady(); __capabilityFault.value = null;
+		const got = healthHandler(__ctx as never) as Response
+const got2 = ((await got.json() as { status: string }).status);
+		expect(got2).toEqual("ok");
+	});
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toBe]", async () => {
+		__resetPhase2StateForTest();
+		const handler = createPhase1PageHandler("svc-tr")( {} as never );
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.status);
+		expect(got2).toEqual(503);
+	});
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toContain]", async () => {
+		__resetPhase2StateForTest();
+		const handler = createPhase1PageHandler("svc-tr")( {} as never );
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.headers.get("content-type"));
+		const __t0_0 = got2;
+		expect(typeof __t0_0 === "string" ? __t0_0 : JSON.stringify(__t0_0)).toContain("text/html");
 	});
-	it("the phase-1 page handler serves the branded waking 503 before phase 2", async () => {
+	it("the phase-1 page handler serves the branded waking 503 before phase 2 [toBeNull]", async () => {
 		__resetPhase2StateForTest();
 		const handler = createPhase1PageHandler("svc-tr")( {} as never );
-		const got = await handler(new Request("http://x.local/"), {} as never);
-		expect(got.status).toBe(503);
-		expect(got.headers.get("content-type")).toContain("text/html");
-		expect(got.headers.get("retry-after")).not.toBeNull();
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (got.headers.get("retry-after"));
+		expect(got2).not.toBeNull();
+		expect(got2).not.toBeUndefined();
 	});
 	it("the phase-1 handler delegates to the real handler once registered", async () => {
 		__resetPhase2StateForTest(); setPageHandler((() => async () => new Response("real-render")) as never);
 		const handler = createPhase1PageHandler("svc-tr")( {} as never );
-		const got = await handler(new Request("http://x.local/"), {} as never);
-		expect(await got.text()).toBe("real-render");
+		const got = await handler(new Request("http://x.local/"), {} as never)
+const got2 = (await got.text());
+		expect(got2).toEqual("real-render");
 	});
 });

package/src/two-phase-readiness.ts

@@ -40,8 +40,9 @@
  */
 
 /**
- * `/health` for a UI service — 200 ONLY once the full app can actually render
- * a page, 503 before that.
+ * `/health` for a UI service — 503 `{"status":"starting"}` until phase 2
+ * completes, then 200: `{"status":"degraded","reason":...}` when the client
+ * build failed, `{"status":"ok"}` otherwise.
  *
  * This endpoint is not decoration: it is the wake gate for every scale-to-zero
  * app. `scala-activator` (`@teamscala/scale-to-zero`) holds the client's TCP
@@ -72,14 +73,22 @@
  * health-gated router) rather than teaching each one its own probe, and it is
  * what `readiness-gated-boot` already requires: "/health returns 503 until
  * ready, 200 after — so it is the real readiness signal", a service being
- * "binary: fully-ready or cleanly-unavailable". A UI service that cannot render
- * is not ready, per `liveness-by-capability-not-process-existence` — liveness is
- * a probe of the capability being REQUESTED, never of process existence or of
- * some other surface that happens to answer.
+ * "binary: fully-ready or cleanly-unavailable".
+ *
+ * DEGRADED COMPLETION IS A 200, NOT A THIRD KIND OF STARTING (measured
+ * 2026-10-14, portal-dev). The degraded path (client build not servable) first
+ * returned before the phase-2 flips, so `/health` answered 503 "starting"
+ * forever — a state the boot KNEW was false. Every health-gated consumer reads
+ * 503 as still-booting: `build_executor::deploy_probe::still_booting` resets
+ * its answered-rounds counter on "503 Service Unavailable", so the dev-update
+ * rehearsal probed a finished boot for 2.5h and never completed; the activator
+ * wake gate would hold a customer forever. The boot's own verdict — degraded,
+ * with the recorded reason in the body — is the honest answer, and it lets
+ * traffic flow to the branded holding page the app itself serves.
  *
  * The early readiness-gate flip is deliberately left alone: it gates the ORPC
  * tool surface, which genuinely IS usable at phase 1. Only this endpoint, whose
- * one consumer contract is "can you serve me a page", is moved to phase 2.
+ * one consumer contract is "has boot completed", is moved to phase 2.
  */
 
 import { buildWakingPageHtml } from "@teamscala/brand/brand/waking-page-html";
@@ -93,6 +102,19 @@ import type { CreatePageHandler } from "./types.ts";
 // This allows the temporary Phase 1 handler to delegate to the real handler once ready.
 let realPageHandler: CreatePageHandler | null = null;
 let fullAppReady = false;
+let degradedReason: string | null = null;
+
+/**
+ * Phase 2 completed DEGRADED: the client build is not servable, so the full
+ * route set never registered — but the boot itself finished, and the process
+ * serves its API, MCP and job surfaces plus the branded holding page for
+ * pages. `fullAppReady` flips true because "starting" is no longer true; the
+ * reason travels beside it so `/health` can report the real verdict.
+ */
+export function markFullAppDegraded(reason: string): void {
+	degradedReason = reason;
+	fullAppReady = true;
+}
 
 /**
  * Set the real page handler (called when Phase 2 completes on an SSR service).
@@ -113,6 +135,7 @@ export function markFullAppReady(): void {
 export function __resetPhase2StateForTest(): void {
 	realPageHandler = null;
 	fullAppReady = false;
+	degradedReason = null;
 }
 
 /**
@@ -124,6 +147,9 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
 
 export function healthHandler(c: Context): Response {
 	if (!fullAppReady) return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
+	if (degradedReason !== null) {
+		return c.json({ status: "degraded", reason: degradedReason });
+	}
 	// Assert the CAPABILITY, not just the phase flag. On 2026-08-20 this returned
 	// 200 through a total outage: the process was up and phase 2 had completed
 	// while the registered client carried no CRUD models, so every data-backed

package/src/types.test.ts

@@ -1,10 +1,10 @@
 /**
  * @status generated — ts-api-smoke template (scala-test-suites
- * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * templates/ts_api_smoke.pkl @1.5.0) over the exports map of @teamscala/service-boot.
  * ./types declares 0 runtime export(s) + 5 type(s);
  * this suite asserts the import resolves, the runtime surface matches
  * exactly, and every export carries its declared kind. Regenerate from
- * inputs/server-service-boot-ts/api_smoke.json (scala-test-suites) — hand edits are
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
  * overwritten.
  */
 
@@ -13,8 +13,7 @@ import { describe, expect, it } from "bun:test";
 const mod = await import("./types");
 
 describe("types exports-map smoke", () => {
-	it("is type-only — the runtime module carries no values", () => {
-		// Declared types: RendererComponentEntry, PageHandlerExtras, CreatePageHandler, PageHandlerConfig, ServiceInstallConfig
+	it("is type-only (declared: RendererComponentEntry, PageHandlerExtras, CreatePageHandler, PageHandlerConfig, ServiceInstallConfig) — the runtime module carries no values", () => {
 		expect(Object.keys(mod).length).toBe(0);
 	});
 });