@teamscala/service-boot 0.23.287 → 0.23.289

package/package.json

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

package/src/pg-boss-mount.ts

@@ -225,6 +225,28 @@ export async function mountPgBoss(
 					handlerSlug: config.handler_slug,
 				});
 			}
+
+			// A SUCCESSFUL mount emitted nothing until now, while every failure
+			// path above recorded an event — so the one state you most need to
+			// confirm ("is this job actually scheduled on this service?") was the
+			// only one with no evidence. Combined with resolveHandler THROWING
+			// into boss.work() rather than warning, that made "never scheduled"
+			// and "fired and threw" externally identical, and cost a
+			// scheduled_job relocation that had to be reverted undiagnosed on
+			// 2026-07-30. Emitting on success makes the mount set queryable
+			// (event-log-is-the-only-durable-event-log).
+			const mounted = jobs[jobs.length - 1];
+			recordEvent({
+				kind: "pgboss.job.mounted",
+				payload: {
+					service: ctx.serviceSlug,
+					slug: entry.slug,
+					queue: queueName,
+					handler: config.handler_slug,
+					cron: mounted?.cron ?? null,
+					interval_seconds: mounted?.intervalSeconds ?? null,
+				},
+			});
 		} catch (err) {
 			// crash-isolation for the mount path: a work()/schedule() failure
 			// (e.g. DB not open, queue conflict) degrades to "this job unavailable"

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

@@ -0,0 +1,84 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Phase-2 step isolation: a client-asset build failure must not prevent
+ * scheduled jobs and pg-boss from mounting.
+ *
+ * Asserted against the SOURCE rather than by booting a service, because the
+ * behaviour is an ordering/error-handling property of buildFullApp and booting
+ * it here would need a database, a registry, a Vite build and a live pg-boss.
+ * The property is structural: buildClientAssets must be inside a try/catch that
+ * appears BEFORE the startScheduledJobs and mountPgBoss calls. That is exactly
+ * what regressed, and a source assertion fails the moment someone re-awaits it
+ * unguarded — which is the regression this locks.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+const src = await Bun.file(new URL("./two-phase-boot.ts", import.meta.url)).text();
+
+/** The body of buildFullApp, where phase-2 ordering lives. */
+function buildFullAppBody(): string {
+	const start = src.indexOf("export async function buildFullApp");
+	expect(start).toBeGreaterThan(-1);
+	return src.slice(start);
+}
+
+describe("phase-2 step isolation", () => {
+	/*
+	 * THE MEASURED REGRESSION. buildClientAssets was awaited unguarded, so a
+	 * throw aborted buildFullApp before startScheduledJobs and mountPgBoss ran.
+	 * The caller's catch logged "Failed to build full app, continuing with
+	 * minimal app", which reads as UI-only degradation while every scheduled job
+	 * and pg-boss handler on the service had silently died.
+	 *
+	 * 2026-07-30: a stale portal-ui artifact importing the retired @teamgbg scope
+	 * threw ENOENT on a missing theme CSS file in scala-agents. No
+	 * "scheduledJobs DONE" line appeared for ~20 minutes across repeated boots,
+	 * the pane-outbox drain never mounted, and the operator's WhatsApp assistant
+	 * went silent — because of a stylesheet. The service reported `online` and
+	 * answered /health throughout.
+	 */
+	test("buildClientAssets is wrapped so its failure cannot abort phase-2", () => {
+		const body = buildFullAppBody();
+		const call = body.indexOf("buildClientAssets(serviceSlug)");
+		expect(call).toBeGreaterThan(-1);
+
+		// A try must open before the call and a catch must follow it, so a throw
+		// is contained rather than propagating out of buildFullApp.
+		const tryBefore = body.lastIndexOf("try {", call);
+		expect(tryBefore).toBeGreaterThan(-1);
+		expect(body.slice(call).indexOf("catch")).toBeGreaterThan(-1);
+	});
+
+	/*
+	 * THE LOAD-BEARING ASSERTION. A `catch` must appear BETWEEN the build call and
+	 * the startScheduledJobs call. That is what makes this test fail if the guard
+	 * is removed: unwrap the await and there is no catch in that span, so the
+	 * expectation cannot be satisfied by some unrelated try/catch elsewhere in the
+	 * function. Ordering alone would NOT catch the regression — the original buggy
+	 * code also had jobs after the build; it just had no catch in between.
+	 */
+	test("a catch sits between the build and the jobs, so a throw cannot skip them", () => {
+		const body = buildFullAppBody();
+		const build = body.indexOf("buildClientAssets(serviceSlug)");
+		const jobs = body.indexOf("startScheduledJobs(");
+		const boss = body.indexOf("mountPgBoss(");
+		expect(build).toBeGreaterThan(-1);
+		expect(jobs).toBeGreaterThan(build);
+		expect(boss).toBeGreaterThan(build);
+
+		const between = body.slice(build, jobs);
+		expect(between).toContain("catch");
+	});
+
+	test("the build failure is logged, so a degraded bundle is never silent", () => {
+		const body = buildFullAppBody();
+		const guardCatch = body.indexOf("catch", body.indexOf("buildClientAssets(serviceSlug)"));
+		// The catch must record something; swallowing here would reproduce the
+		// original invisibility from the other direction.
+		expect(body.slice(guardCatch, guardCatch + 400)).toContain("log.error");
+	});
+});

package/src/two-phase-boot.ts

@@ -396,9 +396,37 @@ export async function buildFullApp(
 	const log = getAppLogger();
 	const { config, serviceSlug, mountRegistry, components, loaded, app: minimalApp } = minimalResult;
 
-	// Client asset building (expensive: Vite build)
-	await buildClientAssets(serviceSlug);
-	log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
+	// Client asset building (expensive: Vite build).
+	//
+	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
+	// This was awaited unguarded, so a throw here aborted buildFullApp before
+	// startScheduledJobs and mountPgBoss ran, and the caller's catch logged
+	// "Failed to build full app, continuing with minimal app" — which reads as a
+	// UI-only degradation while having silently killed every scheduled job and
+	// every pg-boss handler on the service.
+	//
+	// Measured 2026-07-30: a stale @teamscala/portal-ui artifact still importing
+	// the retired @teamgbg scope threw ENOENT on a missing theme CSS file in
+	// scala-agents. Zero "scheduledJobs DONE" lines appeared for ~20 minutes
+	// across repeated boots, the pane-outbox drain never mounted, and the
+	// operator's WhatsApp assistant went silent — because of a stylesheet. The
+	// service stayed `online` and healthy throughout, so nothing surfaced it.
+	//
+	// The steps after this one do not depend on client assets: jobs and pg-boss
+	// need the registry and the DB, not a bundle. Ordering them behind a Vite
+	// build was incidental, so the coupling was never intended.
+	try {
+		await buildClientAssets(serviceSlug);
+		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
+	} catch (error) {
+		// Loud but non-fatal: the tombstone manifest written by buildClientAssets
+		// already makes SSR serve the prior bundle, so degrading here costs the
+		// new bundle, never the background work.
+		log.error(
+			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss (a client-asset failure must not stop background work)`,
+			{ error: error instanceof Error ? error.message : String(error) },
+		);
+	}
 
 	// Scheduled jobs
 	startScheduledJobs(config, mountRegistry, serviceSlug);