@teamscala/service-boot 0.23.343 → 0.23.345

package/package.json

@@ -6,7 +6,7 @@
 	},
 	"name": "@teamscala/service-boot",
 	"type": "module",
-	"version": "0.23.343",
+	"version": "0.23.345",
 	"sideEffects": false,
 	"files": [
 		"src"

package/src/two-phase-boot.d.ts

@@ -18,9 +18,49 @@ import { mountServerPackages } from "./mount-server-packages.ts";
 import type { PageServerDeps } from "./ui-service.ts";
 import type { CreatePageHandler } from "./types.ts";
 /**
- * Set the real page handler (called when Phase 2 completes).
+ * Set the real page handler (called when Phase 2 completes on an SSR service).
+ *
+ * Registering the SSR handler implies the full app is built, so this also flips
+ * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
+ * exists separately. See its note.
  */
 export declare function setPageHandler(handler: CreatePageHandler): void;
+/**
+ * Flip readiness once phase 2 has built the full app.
+ *
+ * SEPARATE FROM `setPageHandler` BECAUSE THE TWO FACTS CAME APART. Readiness
+ * means "phase 2 finished"; the page handler means "this service renders pages
+ * server-side". Every service was SSR, so one flag honestly carried both — until
+ * `render_mode=client` (`granular runtime`) made a service that completes phase 2
+ * and never registers an SSR handler.
+ *
+ * Leaving readiness inside `setPageHandler` made such a service PERMANENTLY
+ * un-ready: `/health` answered `{"status":"starting"}` forever while the process
+ * was healthy and serving. That is the failure `readiness-gated-boot` is written
+ * against — a service must be "binary: fully-ready or cleanly-unavailable", and
+ * a never-ready health signal makes the activator's wake gate and every
+ * health-gated router treat a working service as down.
+ *
+ * Measured 2026-08-07 on scala-agents-ui: boot completed in 5023ms, "Full app
+ * built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and `/health`
+ * still reported starting — while three untouched UI services reported ok.
+ */
+export declare function markFullAppReady(): void;
+/**
+ * Reset both phase-2 flags. TEST-ONLY.
+ *
+ * `fullAppReady` is module state that only ever transitions false -> true in
+ * production, and Bun shares a module instance across every test file in a run —
+ * so the SSR readiness test and the client-only readiness test contaminate each
+ * other purely by file order. Splitting them across files does NOT isolate them;
+ * it only hides the coupling until CI runs them together.
+ *
+ * A test that passes alone and fails in a suite is worse than no test, so the
+ * reset is exported rather than left as an ordering convention nobody can see.
+ * Never called from production code — `setPageHandler`/`markFullAppReady` are
+ * the only writers on the boot path.
+ */
+export declare function __resetPhase2StateForTest(): void;
 /**
  * Get the current page handler state.
  */

package/src/two-phase-boot.ts

@@ -64,13 +64,60 @@ let realPageHandler: CreatePageHandler | null = null;
 let fullAppReady = false;
 
 /**
- * Set the real page handler (called when Phase 2 completes).
+ * Set the real page handler (called when Phase 2 completes on an SSR service).
+ *
+ * Registering the SSR handler implies the full app is built, so this also flips
+ * readiness — but the reverse does NOT hold, which is why `markFullAppReady`
+ * exists separately. See its note.
  */
 export function setPageHandler(handler: CreatePageHandler): void {
 	realPageHandler = handler;
+	markFullAppReady();
+}
+
+/**
+ * Flip readiness once phase 2 has built the full app.
+ *
+ * SEPARATE FROM `setPageHandler` BECAUSE THE TWO FACTS CAME APART. Readiness
+ * means "phase 2 finished"; the page handler means "this service renders pages
+ * server-side". Every service was SSR, so one flag honestly carried both — until
+ * `render_mode=client` (`granular runtime`) made a service that completes phase 2
+ * and never registers an SSR handler.
+ *
+ * Leaving readiness inside `setPageHandler` made such a service PERMANENTLY
+ * un-ready: `/health` answered `{"status":"starting"}` forever while the process
+ * was healthy and serving. That is the failure `readiness-gated-boot` is written
+ * against — a service must be "binary: fully-ready or cleanly-unavailable", and
+ * a never-ready health signal makes the activator's wake gate and every
+ * health-gated router treat a working service as down.
+ *
+ * Measured 2026-08-07 on scala-agents-ui: boot completed in 5023ms, "Full app
+ * built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and `/health`
+ * still reported starting — while three untouched UI services reported ok.
+ */
+export function markFullAppReady(): void {
 	fullAppReady = true;
 }
 
+/**
+ * Reset both phase-2 flags. TEST-ONLY.
+ *
+ * `fullAppReady` is module state that only ever transitions false -> true in
+ * production, and Bun shares a module instance across every test file in a run —
+ * so the SSR readiness test and the client-only readiness test contaminate each
+ * other purely by file order. Splitting them across files does NOT isolate them;
+ * it only hides the coupling until CI runs them together.
+ *
+ * A test that passes alone and fails in a suite is worse than no test, so the
+ * reset is exported rather than left as an ordering convention nobody can see.
+ * Never called from production code — `setPageHandler`/`markFullAppReady` are
+ * the only writers on the boot path.
+ */
+export function __resetPhase2StateForTest(): void {
+	realPageHandler = null;
+	fullAppReady = false;
+}
+
 /**
  * Get the current page handler state.
  */
@@ -504,11 +551,25 @@ export async function buildFullApp(
 			`${Object.keys(components).length} component(s)`,
 	);
 
-	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it
-	setPageHandler(deps.createPageHandler);
-	log.info(
-		`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
-	);
+	// Set the real page handler so the dynamic handler in Phase 1 can delegate to it.
+	// Client-only services (render_mode=client) have no SSR page handler — skip
+	// (they serve via the client bundle, never SSR). Guarded so undefined is a
+	// no-op rather than a crash.
+	if (deps.createPageHandler) {
+		setPageHandler(deps.createPageHandler);
+		log.info(
+			`[two-phase-boot:${serviceSlug}] Real page handler registered - page routes now delegate to full app`,
+		);
+	} else {
+		// The full app IS built — this service simply never renders server-side,
+		// so readiness is flipped directly rather than as a side effect of
+		// registering an SSR handler that will never exist. Without this a
+		// client-only service is permanently un-ready (see markFullAppReady).
+		markFullAppReady();
+		log.info(
+			`[two-phase-boot:${serviceSlug}] Client-only mode (render_mode=client) — no SSR page handler registered`,
+		);
+	}
 
 	const resolvedBlocks = loaded.map((slug) => ({
 		slug,

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

@@ -0,0 +1,77 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * A CLIENT-ONLY service (`render_mode=client`) must reach ready, even though it
+ * never registers an SSR page handler.
+ *
+ * Separate file from `two-phase-health-gate.test.ts` on purpose: `fullAppReady`
+ * is module state that only transitions false -> true and has no reset hook, so
+ * the two ready-paths cannot both be exercised in one module instance. A reset
+ * hook would exist only for tests.
+ *
+ * THE REGRESSION THIS LOCKS (measured 2026-08-07 on scala-agents-ui). Readiness
+ * used to be flipped INSIDE `setPageHandler`, which was honest while every
+ * service was SSR. `render_mode=client` made a service that completes phase 2
+ * and never calls it, so `/health` answered `{"status":"starting"}` FOREVER
+ * while the process was healthy and serving — boot completed in 5023ms, "Full
+ * app built: 50 block(s)" logged, `GET /` correctly 302'd to sign-in, and three
+ * untouched UI services reported ok beside it.
+ *
+ * That is precisely what `readiness-gated-boot` forbids ("binary: fully-ready or
+ * cleanly-unavailable"): a permanently-un-ready health signal makes the
+ * activator's wake gate and every health-gated router treat a working service as
+ * down. Exercised through a real Hono request against the REAL exported handler
+ * (`proxy-is-not-behaviour`) — a source grep would prove the call exists, never
+ * that the endpoint answers 200.
+ */
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import {
+	__resetPhase2StateForTest,
+	getPageHandlerState,
+	healthHandler,
+	markFullAppReady,
+} from "./two-phase-boot.ts";
+
+/** Mount the real handler exactly as buildMinimalApp does. */
+const app = new Hono().get("/health", healthHandler);
+
+describe("/health for a client-only service", () => {
+	// Bun shares one module instance across every test file in a run, so the SSR
+	// readiness test's setPageHandler leaks into this file when both run together.
+	// Without this reset the suite passes file-by-file and fails in CI.
+	beforeAll(() => {
+		__resetPhase2StateForTest();
+	});
+
+	test("before phase 2 completes it reports 503, not ready", async () => {
+		expect(getPageHandlerState().ready).toBe(false);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(503);
+		expect(await res.json()).toEqual({ status: "starting" });
+	});
+
+	test("reaches ready without an SSR page handler", async () => {
+		// The real client-only phase-2 path: buildFullApp finishes and marks the
+		// app ready WITHOUT setPageHandler, because there is no SSR handler.
+		markFullAppReady();
+
+		const state = getPageHandlerState();
+		expect(state.ready).toBe(true);
+		// The discriminator: ready is true while hasHandler stays false. Asserting
+		// both is what separates this from the SSR path — a fix that flipped ready
+		// by registering a dummy handler would pass `ready` and fail here.
+		expect(state.hasHandler).toBe(false);
+
+		const res = await app.request("/health");
+
+		expect(res.status).toBe(200);
+		expect(res.ok).toBe(true);
+		expect(await res.json()).toEqual({ status: "ok" });
+	});
+});

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

@@ -27,9 +27,14 @@
  * 137ms warm), which is why one app looked healthy and the others did not.
  */
 
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
 import { Hono } from "hono";
-import { healthHandler, setPageHandler, getPageHandlerState } from "./two-phase-boot.ts";
+import {
+	__resetPhase2StateForTest,
+	getPageHandlerState,
+	healthHandler,
+	setPageHandler,
+} from "./two-phase-boot.ts";
 
 /** Mount the real handler exactly as buildMinimalApp does. */
 const app = new Hono().get("/health", healthHandler);
@@ -41,6 +46,12 @@ const app = new Hono().get("/health", healthHandler);
  * hook and adding one would exist only for tests.
  */
 describe("/health is gated on page-serving readiness", () => {
+	// Bun shares one module instance across test files, so a sibling file that
+	// marks the app ready would otherwise decide this file's first assertion.
+	beforeAll(() => {
+		__resetPhase2StateForTest();
+	});
+
 	test("before the phase-2 swap it reports 503, not ready", async () => {
 		expect(getPageHandlerState().ready).toBe(false);