@teamscala/service-boot 0.23.535 → 0.23.537

package/src/pg-boss-mount.ts

@@ -3,13 +3,14 @@
  * @status handwritten
  */
 
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { validateRow } from "@teamscala/db-validation/validate-row";
+import type { ScheduledJobConfig } from "@teamscala/registry-schemas/registry-schemas/scheduled-job";
+import { validateRow } from "@teamscala/row-validation/validate-row";
 import { pgSslCompatUrl } from "@teamscala/db/provider/pg-ssl-compat";
 import { getAllEntries } from "@teamscala/db/registry/accessors";
 import type { RegistryEntry } from "@teamscala/db/registry/types";
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { getPrisma } from "@teamscala/db/prisma-registry";
 import type { JobHandler } from "@teamscala/os/runtime-contracts/mount-context";
 import type { ScheduleOptions } from "pg-boss";
 import { PgBoss } from "pg-boss";
@@ -77,6 +78,98 @@ async function resolveHandler(
 	return await handler({ config, jobData, sendJob: (queue, data, options) => boss.send(queue, data, options) });
 }
 
+async function recordFire(jobSlug: string, queueName: string): Promise<string | null> {
+	try {
+		const row = await getPrisma().scheduledJobRuns.create({
+			data: { job_slug: jobSlug, queue_name: queueName, status: "active", attempt: 1 },
+		});
+		return String(row.id);
+	} catch (err) {
+		getAppLogger().warn(`[pg-boss-mount:${jobSlug}] scheduled_job_runs fire write failed`, {
+			error: err instanceof Error ? err.message : String(err),
+		});
+		return null;
+	}
+}
+
+async function recordOutcome(
+	runId: string | null,
+	jobSlug: string,
+	status: "completed" | "error",
+	error: string | null,
+	result: unknown,
+): Promise<void> {
+	if (runId === null) return;
+	try {
+		await getPrisma().scheduledJobRuns.update({
+			where: { id: runId },
+			data: { status, completed_at: new Date(), error, result },
+		});
+	} catch (err) {
+		getAppLogger().warn(`[pg-boss-mount:${jobSlug}] scheduled_job_runs outcome write failed`, {
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}
+
+async function expirePriorProcessRuns(slugs: string[]): Promise<void> {
+	for (const slug of slugs) {
+		try {
+			await getPrisma().scheduledJobRuns.updateMany({
+				where: { job_slug: slug, status: "active" },
+				data: {
+					status: "expired",
+					completed_at: new Date(),
+					error: "owning service process exited before writing an outcome",
+				},
+			});
+		} catch (err) {
+			getAppLogger().warn(`[pg-boss-mount:${slug}] scheduled_job_runs prior-process expiry failed`, {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+}
+
+const SINGLETON_POLICY = "singleton";
+
+async function scheduleRow(
+	boss: PgBoss,
+	slug: string,
+	config: ScheduledJobConfig,
+	cron: string,
+	scheduleOpts: ScheduleOptions,
+): Promise<void> {
+	const queueName = config.queue_name;
+	if (!config.singleton) {
+		await boss.schedule(queueName, cron, null, scheduleOpts);
+		return;
+	}
+
+	scheduleOpts.singletonKey = slug;
+
+	const [before] = await boss.getQueueStats(queueName);
+	const staleQueued = before?.queuedCount ?? 0;
+	if (staleQueued > 0) {
+		await boss.deleteQueuedJobs(queueName);
+		const [after] = await boss.getQueueStats(queueName);
+		const drained = staleQueued - (after?.queuedCount ?? staleQueued);
+		recordEvent({
+			kind: after?.queuedCount === 0 ? "pgboss.queue.backlog-drained" : "pgboss.queue.backlog-drain-failed",
+			payload: {
+				queue: queueName,
+				slug,
+				stale_queued: staleQueued,
+				drained,
+				remaining: after?.queuedCount ?? null,
+				reason: "singleton-subscription-before-backlog-drain",
+			},
+		});
+	}
+
+	await boss.schedule(queueName, cron, null, scheduleOpts);
+}
+
 export async function mountPgBoss(
 	ctx: PgBossMountContext,
 ): Promise<PgBossMountResult> {
@@ -93,6 +186,7 @@ export async function mountPgBoss(
 
 	const log = getAppLogger();
 	const jobs: MountedJob[] = [];
+	await expirePriorProcessRuns(scheduledEntries.map((e) => e.slug));
 
 	const boss = new PgBoss({
 		useListenNotify: false,
@@ -143,11 +237,19 @@ export async function mountPgBoss(
 		const queueName = config.queue_name;
 
 		try {
-			await boss.createQueue(queueName);
+			await boss.createQueue(queueName, { policy: config.singleton ? SINGLETON_POLICY : undefined });
 			await boss.work(queueName, async (jobs) => {
 				let result: unknown;
 				for (const job of jobs) {
-					result = await resolveHandler(boss, ctx.jobHandlers, config.handler_slug, config, job.data);
+					const runId = await recordFire(entry.slug, queueName);
+					try {
+						result = await resolveHandler(boss, ctx.jobHandlers, config.handler_slug, config, job.data);
+						await recordOutcome(runId, entry.slug, "completed", null, result);
+					} catch (err) {
+						const outcomeError = err instanceof Error ? err.message : String(err);
+						await recordOutcome(runId, entry.slug, "error", outcomeError, null);
+						throw err;
+					}
 				}
 				return jobs.length === 1 ? result : undefined;
 			});
@@ -159,7 +261,7 @@ export async function mountPgBoss(
 					scheduleOpts.retryDelay = config.retry.backoff_seconds;
 					scheduleOpts.retryBackoff = true;
 				}
-				await boss.schedule(queueName, config.cron, null, scheduleOpts);
+				await scheduleRow(boss, entry.slug, config, config.cron, scheduleOpts);
 				jobs.push({
 					queueName,
 					handlerSlug: config.handler_slug,
@@ -173,7 +275,7 @@ export async function mountPgBoss(
 					scheduleOpts.retryDelay = config.retry.backoff_seconds;
 					scheduleOpts.retryBackoff = true;
 				}
-				await boss.schedule(queueName, cron, null, scheduleOpts);
+				await scheduleRow(boss, entry.slug, config, cron, scheduleOpts);
 				jobs.push({
 					queueName,
 					handlerSlug: config.handler_slug,
@@ -214,12 +316,14 @@ export async function mountPgBoss(
 
 	try {
 		const backedScheduleNames = new Set(
-			allEntries.flatMap((e) => {
-				const cfg = e.config as { queue_name?: string } | null;
-				return [e.slug, cfg?.queue_name].filter(
-					(n): n is string => typeof n === "string" && n.length > 0,
-				);
-			}),
+			allEntries
+				.filter((e) => (e.type as string) === "scheduled_job" && e.is_active)
+				.flatMap((e) => {
+					const cfg = e.config as { queue_name?: string } | null;
+					return [e.slug, cfg?.queue_name].filter(
+						(n): n is string => typeof n === "string" && n.length > 0,
+					);
+				}),
 		);
 		const liveSchedules = await boss.getSchedules();
 		for (const sched of liveSchedules) {
@@ -227,13 +331,18 @@ export async function mountPgBoss(
 			log.warn(
 				`[pg-boss:${ctx.serviceSlug}] unscheduling orphaned cron "${sched.name}" (no active registry row backs it — drift)`,
 			);
-			await boss.unschedule(sched.name);
+			await boss.unschedule(sched.name, sched.key);
+			const gone = await boss.getSchedule(sched.name, sched.key);
 			recordEvent({
-				kind: "pgboss.schedule.unscheduled",
+				kind: gone === null ? "pgboss.schedule.unscheduled" : "pgboss.schedule.unschedule-failed",
 				payload: {
 					service: ctx.serviceSlug,
 					name: sched.name,
-					reason: "orphaned-no-active-backing-row",
+					key: sched.key,
+					reason:
+						gone === null
+							? "orphaned-no-active-backing-row"
+							: "unschedule-readback-row-still-present",
 				},
 			});
 		}

package/src/read-html-template.ts

@@ -4,7 +4,6 @@
  */
 
 import { createCache } from "@teamscala/cache/create-cache";
-import { readClientBuildStatus } from "./build-client-assets/manifest.ts";
 import { themeFontsLink } from "./theme-fonts-link.ts";
 import { join } from "node:path";
 
@@ -54,11 +53,6 @@ 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())) return null;
 	try {
@@ -67,15 +61,12 @@ async function loadManifest(): Promise<AssetManifest | null> {
 			return { stylesPath: parsed.stylesPath, hydratePath: parsed.hydratePath };
 		}
 	} catch {
-		// fall through to null — gate + boot log will name the reason.
+		return null;
 	}
 	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();
 }
 
@@ -94,22 +85,7 @@ export async function readHtmlTemplate(): Promise<string> {
 	let html = PAGE_DOCUMENT
 		.replace(/\{\{stylesPath\}\}/g, manifest.stylesPath)
 		.replace(/\{\{hydratePath\}\}/g, manifest.hydratePath)
-		// The head's font families derive from the css_theme row (one source);
-		// captured at cache build — boot-time semantics, a row edit reaches the
-		// envelope on the next service restart.
 		.replace("<!--theme-fonts-->", () => themeFontsLink());
-	// 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
-	// probe). `x-` prefix keeps it out of any standard meta namespace.
-	const status = await readClientBuildStatus();
-	if (status.failed) {
-		const reason = (status.reason ?? "unknown").replace(/"/g, "'").slice(0, 200);
-		const meta = `<meta name="x-client-build-status" content="failed" data-reason="${reason}" data-at="${status.at ?? ""}">`;
-		html = html.includes("</head>")
-			? html.replace("</head>", `${meta}</head>`)
-			: `${meta}${html}`;
-	}
 	htmlCache.set(manifestCacheKey(), { html, manifestMtime });
 	return html;
 }

package/src/register-page-server-client.ts

@@ -45,7 +45,7 @@ export async function registerPageServerClient(
 				"@teamscala/db/registry/errors"
 			);
 			const { ServiceSchemaConfigSchema } = await import(
-				"@teamscala/db-validation/registry-schemas/service-schema"
+				"@teamscala/registry-schemas/registry-schemas/service-schema"
 			);
 			try {
 				const row = await loadOptionalRegistryConfig(
@@ -86,7 +86,7 @@ export async function registerPageServerClient(
 			"@teamscala/db/registry/load-config"
 		);
 		const { PlatformIdentitySchema } = await import(
-			"@teamscala/db-validation/registry-schemas/platform-identity"
+			"@teamscala/registry-schemas/registry-schemas/platform-identity"
 		);
 		const platformIdentity = await loadRegistryConfig(
 			"config",

package/src/register-registry-page-route/live-loader-config.test.ts

@@ -100,7 +100,6 @@ mock.module("@teamscala/logger/app-loggers", () => ({
 const { registerRegistryPageRoute } = await import(
 	"../register-registry-page-route.ts"
 );
-const { fingerprintLoaderConfig } = await import("./live-loader-config.ts");
 const { Hono } = await import("hono");
 
 afterEach(() => {
@@ -189,15 +188,4 @@ describe("live loader config — per-request read (boot-baked-loader fix)", () =
 		const res = await requestRoute(app);
 		expect(res.status).toBe(500);
 	});
-
-	test("the graphKey fingerprint changes with the config and is key-order stable", () => {
-		const a = fingerprintLoaderConfig({ sources: [{ key: "page" }] });
-		const b = fingerprintLoaderConfig({
-			sources: [{ key: "page" }, { key: "agreement" }],
-		});
-		expect(a).not.toBe(b);
-		expect(fingerprintLoaderConfig({ a: 1, b: 2 })).toBe(
-			fingerprintLoaderConfig({ b: 2, a: 1 }),
-		);
-	});
 });

package/src/register-registry-page-route/live-loader-config.ts

@@ -4,7 +4,7 @@
  */
 
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
-import { ResourceLoaderConfigSchema } from "@teamscala/db-validation/registry-schemas/resource-loader";
+import { ResourceLoaderConfigSchema } from "@teamscala/registry-schemas/registry-schemas/resource-loader";
 import type { ResourceLoaderKey } from "@teamscala/db/registry/generated/resource-loader";
 import * as v from "valibot";
 

package/src/register-registry-page-route/resolve-request-graph.ts

@@ -5,7 +5,7 @@
 
 import type { PageRouteConfig } from "../register-registry-page-route.ts";
 import * as v from "valibot";
-import type { ResourceLoaderConfigSchema } from "@teamscala/db-validation/registry-schemas/resource-loader";
+import type { ResourceLoaderConfigSchema } from "@teamscala/registry-schemas/registry-schemas/resource-loader";
 import { resolveFromLoaderConfig } from "../page-server-loader-graph.ts";
 import { decideContentPageFloor } from "../content-page-floor.ts";
 import { PrimaryResourceMissingError } from "../resource-not-found.ts";

package/src/register-registry-page-route.ts

@@ -5,9 +5,9 @@
 
 import type { InferOutput } from "valibot";
 import type { RenderModeLiteral } from "./page-route-shell-types.ts";
-import { PageRouteConfigSchema } from "@teamscala/db-validation/registry-schemas/page-route";
-import { ResourceLoaderConfigSchema } from "@teamscala/db-validation/registry-schemas/resource-loader";
-import { FeatureFlagConfigSchema } from "@teamscala/db-validation/registry-schemas/feature-flag";
+import { PageRouteConfigSchema } from "@teamscala/registry-schemas/registry-schemas/page-route";
+import { ResourceLoaderConfigSchema } from "@teamscala/registry-schemas/registry-schemas/resource-loader";
+import { FeatureFlagConfigSchema } from "@teamscala/registry-schemas/registry-schemas/feature-flag";
 import {
 	loadRegistryConfig,
 	loadRegistryConfigsByType,

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

@@ -35,7 +35,7 @@ export async function buildFullApp(
 		log.info(`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets DONE`);
 	} catch (error) {
 		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)`,
+			`[two-phase-boot:${serviceSlug}] phase-2 step: buildClientAssets FAILED — continuing to scheduled jobs and pg-boss; the verification gate below then refuses readiness`,
 			{ error: error instanceof Error ? error.message : String(error) },
 		);
 	}
@@ -94,9 +94,9 @@ export async function buildFullApp(
 	}));
 
 	return {
-		app: minimalApp, // Same app reference, all routes already registered
+		app: minimalApp,
 		blocks: resolvedBlocks,
-		routes: [], // Routes already registered in Phase 1
+		routes: [],
 		pgBossJobs,
 	};
 }

package/src/ui-service.ts

@@ -3,23 +3,7 @@
  * @status handwritten
  */
 
-/**
- * Boots a UI service using two-phase boot for fast availability.
- *
- * Phase 1 (fast): Build and serve minimal tool-only app (ORPC, data routes,
- * auth gates). This becomes available within ~10s, enabling the MCP tool
- * surface to accept requests immediately after restart.
- *
- * Phase 2 (background): Build full app (pages, hydration) and atomically swap
- * it in. The readiness gate flips to ready after Phase 1, not Phase 2.
- *
- * The interim mitigation (503 + gateway retry + circuit breaker) remains in
- * place and is NOT undone.
- */
-
-
-
-import { recordEvent } from "@teamscala/event-log/record-event";
+import { recordEventDurable } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { Hono } from "hono";
@@ -43,17 +27,9 @@ export interface UiServiceBootResult {
 	app: Hono;
 }
 
-/**
- * Page-server symbols injected by the caller. service-boot is tier 4
- * (server) and must not import from tier 2 (`@teamscala/service-runtime`)
- * per `installer-and-runtime` Rule 1. The runtime's bin entrypoint
- * boot pipeline imports these from `page-server/` (same package —
- * legal) and passes them down here.
- */
 export interface PageServerDeps {
 	createPageHandler: import("./types.ts").CreatePageHandler;
 	upgradeWebSocket?: UpgradeWebSocket;
-	/** Shared Prisma client threaded to mounts via ctx.getSharedDb (optional). */
 	getSharedDb?: () => unknown;
 }
 
@@ -129,25 +105,24 @@ export async function bootUiService(
 				`[ui-service-boot:${serviceSlug}] Full app swapped in after ${fullDuration}ms (${fullDuration - minimalDuration}ms after minimal app)`,
 			);
 		} catch (err) {
-			const reason = err instanceof Error ? err.message : String(err);
+			const message = err instanceof Error ? err.message : String(err);
 			log.error(
-				`[ui-service-boot:${serviceSlug}] Failed to build full app, continuing with minimal app: ${reason}`,
+				`[ui-service-boot:${serviceSlug}] Phase-2 boot failed — exiting so the supervisor restarts a service that serves a fresh client build: ${message}`,
 			);
-			recordEvent({
-				kind: "boot.client-build-failed",
-				payload: {
-					service: serviceSlug,
-					reason: reason.slice(0, 2000),
-					at: new Date().toISOString(),
-				},
+			await recordEventDurable({
+				id: crypto.randomUUID(),
+				kind: "service.boot.failed",
+				payload: { service_slug: serviceSlug, phase: "phase-2", message: message.slice(0, 2000) },
+				occurredAt: new Date(),
 			});
+			process.exit(1);
 		}
 	})();
 
 	return {
 		kind: "ui",
-		blocks: [], // Will be populated when full app builds
-		routes: [], // Will be populated when full app builds
+		blocks: [],
+		routes: [],
 		port,
 		app: minimalAppResult.app,
 	};

package/src/build-client-assets/source-candidates.test.ts

@@ -1,60 +0,0 @@
-// @system codegen
-// @status generated
-// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
-//
-// This suite's assertions are OWNED by the codegen band: the band module
-// carries them verbatim, this file is the emission, and hand edits here are
-// overwritten on the next run. The rationale each assertion carries moved
-// with it into the band.
-
-import { describe, expect, test } from "bun:test";
-import { mkdir, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { scanSourceCandidates } from "./source-candidates.ts";
-
-const noopLog = { warn: () => {}, info: () => {}, error: () => {} } as never;
-
-async function makeSourceTree(tag: string, files: Record<string, string>) {
-	const root = join(tmpdir(), `source-candidates-${tag}-${process.pid}`);
-	await rm(root, { recursive: true, force: true });
-	for (const [rel, content] of Object.entries(files)) {
-		const p = join(root, rel);
-		await mkdir(p.slice(0, p.lastIndexOf("/")), { recursive: true });
-		await Bun.file(p).write(content);
-	}
-	return root;
-}
-
-describe("scanSourceCandidates", () => {
-	test("scans a DIRECTORY source and extracts utility candidates", async () => {
-		const root = await makeSourceTree("dir-src", {
-			"src/Button.tsx": 'export const k = "h-12 px-6 text-base rounded-md";',
-		});
-		const candidates = await scanSourceCandidates(
-			[{ base: root, pattern: "src" }],
-			noopLog,
-		);
-		expect(candidates).toContain("h-12");
-		expect(candidates).toContain("px-6");
-		expect(candidates).toContain("text-base");
-		expect(candidates).toContain("rounded-md");
-		await rm(root, { recursive: true, force: true });
-	});
-
-	test("skips an absent source silently instead of zeroing the scan", async () => {
-		const root = await makeSourceTree("absent-src", {
-			"src/Keep.tsx": "flex gap-2",
-		});
-		const candidates = await scanSourceCandidates(
-			[
-				{ base: root, pattern: "src" },
-				{ base: root, pattern: "does-not-exist" },
-			],
-			noopLog,
-		);
-		expect(candidates).toContain("flex");
-		expect(candidates).toContain("gap-2");
-		await rm(root, { recursive: true, force: true });
-	});
-});

package/src/build-client-assets/source-candidates.ts

@@ -1,76 +0,0 @@
-/**
- * @system service-boot
- * @status handwritten
- */
-
-import { resolve } from "node:path";
-import { stat } from "node:fs/promises";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-
-async function existsStat(path: string): Promise<boolean> {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-const SCAN_EXTS = new Set([
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".mjs",
-	".cjs",
-	".html",
-	".md",
-	".mdx",
-]);
-const CANDIDATE_RE = /[A-Za-z0-9_:/[\].%#!,&-]+/g;
-
-export async function scanSourceCandidates(
-	sources: Array<{ base: string; pattern: string; negated?: boolean }>,
-	log: ReturnType<typeof getAppLogger>,
-): Promise<string[]> {
-	const candidates = new Set<string>();
-	for (const src of sources) {
-		if (src.negated) continue;
-		let root: string;
-		try {
-			root = resolve(src.base, src.pattern);
-		} catch {
-			continue;
-		}
-		if (!await existsStat(root)) continue;
-		const rootInNodeModules = root.includes("/node_modules/");
-		try {
-			const glob = new Bun.Glob("**/*");
-			for await (const file of glob.scan({
-				cwd: root,
-				absolute: true,
-				onlyFiles: true,
-			})) {
-				if (!rootInNodeModules && file.includes("/node_modules/")) continue;
-				if (file.includes("/dist/") || file.endsWith(".d.ts")) continue;
-				const dot = file.lastIndexOf(".");
-				if (dot < 0 || !SCAN_EXTS.has(file.slice(dot))) continue;
-				let text: string;
-				try {
-					text = await Bun.file(file).text();
-				} catch {
-					continue;
-				}
-				const matched = text.match(CANDIDATE_RE);
-				if (matched) for (const t of matched) candidates.add(t);
-			}
-		} catch (err) {
-			log.warn(
-				`[build-client-assets] candidate scan skipped ${root}: ${
-					err instanceof Error ? err.message : String(err)
-				}`,
-			);
-		}
-	}
-	return [...candidates];
-}