@teamscala/service-boot 0.23.431 → 0.23.432

package/src/two-phase-readiness.ts

@@ -9,30 +9,6 @@
  * handler once phase 2 completes. Every reader goes through these exports.
  */
 
-import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
-import { WAKING_RETRY_SECONDS } from "@teamscala/os/brand/waking-page-budget.generated";
-import type { Context } from "hono";
-import { getServerClientCapabilityFault } from "./page-server-orpc/server-client.ts";
-import { resolveErrorPageLogo } from "./resource-not-found.ts";
-import type { CreatePageHandler } from "./types.ts";
-
-// Module-level storage for the real page handler, updated when Phase 2 completes.
-// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
-let realPageHandler: CreatePageHandler | null = null;
-let fullAppReady = false;
-
-/**
- * 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.
  *
@@ -53,10 +29,10 @@ export function setPageHandler(handler: CreatePageHandler): void {
  * 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;
-}
 
+// Why: Flip readiness once phase 2 has built the full app.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * Reset both phase-2 flags. TEST-ONLY.
  *
@@ -71,18 +47,10 @@ export function markFullAppReady(): void {
  * 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.
- */
-export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
-	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
-}
 
+// Why: Reset both phase-2 flags. TEST-ONLY.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * `/health` for a UI service — 200 ONLY once the full app can actually render
  * a page, 503 before that.
@@ -125,6 +93,50 @@ export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
  * 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.
  */
+
+// Why: `/health` for a UI service — 200 ONLY once the full app can …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
+import { WAKING_RETRY_SECONDS } from "@teamscala/os/brand/waking-page-budget.generated";
+import type { Context } from "hono";
+import { getServerClientCapabilityFault } from "./page-server-orpc/server-client.ts";
+import { resolveErrorPageLogo } from "./resource-not-found.ts";
+import type { CreatePageHandler } from "./types.ts";
+
+// Module-level storage for the real page handler, updated when Phase 2 completes.
+// This allows the temporary Phase 1 handler to delegate to the real handler once ready.
+let realPageHandler: CreatePageHandler | null = null;
+let fullAppReady = false;
+
+/**
+ * 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();
+}
+
+export function markFullAppReady(): void {
+	fullAppReady = true;
+}
+
+export function __resetPhase2StateForTest(): void {
+	realPageHandler = null;
+	fullAppReady = false;
+}
+
+/**
+ * Get the current page handler state.
+ */
+export function getPageHandlerState(): { ready: boolean; hasHandler: boolean } {
+	return { ready: fullAppReady, hasHandler: realPageHandler !== null };
+}
+
 export function healthHandler(c: Context): Response {
 	if (!fullAppReady) return c.json({ status: "starting" }, 503, { "Retry-After": "1" });
 	// Assert the CAPABILITY, not just the phase flag. On 2026-08-20 this returned

package/src/ui-service.ts

@@ -8,6 +8,56 @@
  * served by @teamscala/service-runtime/serve (one Bun.serve in dev and prod).
  */
 
+/**
+ * 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.
+ */
+
+// Why: Boots a UI service using two-phase boot for fast availabilit…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
+	// the same one the backend branch uses. The registry wins wherever it has an
+	// opinion and a contradicting PORT env is reported, never silently obeyed —
+	// full reasoning in that file.
+	//
+	// This branch previously took `process.env.PORT` unconditionally, which is
+	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
+	// leaked env and silently split that daemon's traffic (2026-07-31). On the
+	// dev host the registry wins a conflict (below). On Railway the injected PORT
+	// wins instead — Railway healthchecks exactly that port, and the row's port
+	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
+	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
+	// path in the resolver).
+
+// Why: Resolve the listen port through the SHARED resolver (`resolv…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
+			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
+			// The minimal-app fallback keeps serving SSR from the LAST-successful
+			// manifest (now a tombstone, see build-client-assets.ts), so the page
+			// looks "up" while the client bundle is stale. Without this signal the
+			// failure is buried in boot stderr and a published fix that reached
+			// node_modules but failed to bundle ships invisibly stale (the
+			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
+			// served pre-fix bytes across restarts while node_modules was
+			// mid-install). The boot.client-build-failed event routes into
+			// event-log's 7-day retention → surfaces in GlitchTip as an incident
+			// trail the operator actually watches.
+
+// Why: NO-SILENT-REVERTS — surface the failed client build to OBSER…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
@@ -46,19 +96,6 @@ export interface PageServerDeps {
 	getSharedDb?: () => unknown;
 }
 
-/**
- * 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.
- */
 export async function bootUiService(
 	config: ServiceInstallConfig,
 	serviceSlug: string,
@@ -77,19 +114,6 @@ export async function bootUiService(
 		deps.getSharedDb,
 	);
 
-	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
-	// the same one the backend branch uses. The registry wins wherever it has an
-	// opinion and a contradicting PORT env is reported, never silently obeyed —
-	// full reasoning in that file.
-	//
-	// This branch previously took `process.env.PORT` unconditionally, which is
-	// how scala-quiz (declared 5203) booted onto session-picker's 3021 from a
-	// leaked env and silently split that daemon's traffic (2026-07-31). On the
-	// dev host the registry wins a conflict (below). On Railway the injected PORT
-	// wins instead — Railway healthchecks exactly that port, and the row's port
-	// is the service's LOCAL dev port (e.g. portal 5200), so binding it on Railway
-	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
-	// path in the resolver).
 	const isRailway = Boolean(process.env.RAILWAY_ENVIRONMENT);
 	const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
 	// The APP binds its PRIVATE port (app_port) when present — for scale-to-zero
@@ -160,18 +184,6 @@ export async function bootUiService(
 			log.error(
 				`[ui-service-boot:${serviceSlug}] Failed to build full app, continuing with minimal app: ${reason}`,
 			);
-			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
-			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
-			// The minimal-app fallback keeps serving SSR from the LAST-successful
-			// manifest (now a tombstone, see build-client-assets.ts), so the page
-			// looks "up" while the client bundle is stale. Without this signal the
-			// failure is buried in boot stderr and a published fix that reached
-			// node_modules but failed to bundle ships invisibly stale (the
-			// scala-agents 2026-07-18 incident: ui-foundation@3.4.5 installed but
-			// served pre-fix bytes across restarts while node_modules was
-			// mid-install). The boot.client-build-failed event routes into
-			// event-log's 7-day retention → surfaces in GlitchTip as an incident
-			// trail the operator actually watches.
 			recordEvent({
 				kind: "boot.client-build-failed",
 				payload: {

package/src/handlers/pane-outbox-drain.ts

@@ -1,39 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `pane-outbox-drain` pg-boss handler — delivers messages the operator's
- * WhatsApp PA queues into `pane_messages` to the addressed agent pane.
- *
- * WHY THE REGISTRATION LIVES HERE AND THE WORK LIVES IN @teamscala/channel.
- * The delivery itself belongs to the channel capability, so `paneOutboxDrainTick`
- * is owned by `@teamscala/channel` beside the dispatch handler it calls. But
- * `pgBossHandlerRegistry` is SERVER tier and `@teamscala/channel` is ADAPTER
- * tier, so the channel package cannot register a pg-boss handler without an
- * upward dependency — forbidden by `vertical-dependency-only`, which has no
- * carve-out. server → adapter is DOWNWARD, so the registration sits here and
- * imports the work, exactly as the four sibling handlers in this directory do.
- *
- * The MountContext route (`ctx.registerScheduledJob`) is tier-legal but NOT
- * usable: `start-scheduled-jobs.ts` offers only `long_running` (invoked once,
- * runs forever) and `recurring` (whose handlers "manage their own setInterval").
- * Both are the in-process timer that `pg-boss-for-background-work` forbids and
- * that the timer half of `in-memory-state-is-not-durable` describes — a timer
- * only fires if its host outlives it, so on a restart-prone service it silently
- * never runs while logging that it started. pg-boss is the only durable option,
- * because the job row outlives any worker.
- *
- * Scoped to scala-channel by its `scheduled_job` row's `service_slug`, so it
- * runs on the service that owns the channel rather than on scala-agents, whose
- * UI-asset build failures used to take PA delivery down with them.
- *
- * Registered under slug `@teamscala/service-boot:pane-outbox-drain`.
- */
-import { paneOutboxDrainTick } from "@teamscala/channel/pane-outbox/drain-tick";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-
-pgBossHandlerRegistry.register(
-	"@teamscala/service-boot:pane-outbox-drain",
-	paneOutboxDrainTick,
-);

package/src/handlers/prune-stale-data.ts

@@ -1,110 +0,0 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * The `db-prune-stale-data` pg-boss handler. Reads the `retention` map from the
- * `scheduled_job` row config and prunes stale rows per entry.
- *
- * Writes use Prisma ORM methods (deleteMany/updateMany) via the prisma-registry
- * client — NEVER raw SQL. The `@teamscala/db` client carries the `blockRawSqlWrites`
- * audit extension: `$executeRaw`/`$executeRawUnsafe` are blocked so every write
- * is audited; ORM methods are the canonical audited path.
- *
- * SAFETY — identifier allowlist: each retention key selects a FIXED, hardcoded
- * Prisma model + field (table/field names are literal in code, never derived
- * from the row); the row's value (a duration string) is parsed to a cutoff Date.
- * A row can therefore never inject arbitrary SQL or address an unvetted model.
- * Keys not in the allowlist are skipped + logged.
- *
- * `audit_trail.*` is INTENTIONALLY EXCLUDED: `audit-trail-permanent` (critical)
- * forbids any DELETE FROM audit_trail. The legacy row's
- * `audit_trail.sync_entities: "delete all"` entry is stale drift from before
- * the 2026-06-19 hardening — surfaced (skipped + warned), never executed.
- *
- * Registered under slug `@teamscala/service-boot:prune-stale-data`.
- */
-import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
-import { Prisma } from "@teamscala/db/client";
-import { getPrisma } from "@teamscala/db/prisma-registry";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
-
-const DURATION_RE = /^(\d+)\s+(second|minute|hour|day|week|month|year)s?$/;
-const UNIT_TO_MS: Record<string, number> = {
-	second: 1_000,
-	minute: 60_000,
-	hour: 3_600_000,
-	day: 86_400_000,
-	week: 604_800_000,
-	month: 2_592_000_000,
-	year: 31_536_000_000,
-};
-
-type PrismaClient = ReturnType<typeof getPrisma>;
-type PruneOp = (prisma: PrismaClient, cutoff: Date) => Promise<number>;
-
-// Fixed ops — model + field names literal in code, cutoff Date is the only
-// variable. Adding a prunable target = adding an entry here (and confirming the
-// model/field + audit-trail-permanent scope).
-const PRUNE_OPS: Record<string, PruneOp> = {
-	"fleet_run_events": async (prisma, cutoff) =>
-		(await prisma.fleet_run_events.deleteMany({ where: { created_at: { lt: cutoff } } })).count,
-	"fleet_run_transitions": async (prisma, cutoff) =>
-		(await prisma.fleet_run_transitions.deleteMany({ where: { created_at: { lt: cutoff } } })).count,
-	// Null out the bulky transcript JSON of old runs — keep the run row itself.
-	// A nullable-Json column requires Prisma's DbNull sentinel (bare `null` is
-	// ambiguous: JSON null vs SQL NULL); DbNull sets the column to SQL NULL.
-	// Prisma namespace is re-exported from @teamscala/db/client.
-	"fleet_agent_runs.transcript": async (prisma, cutoff) =>
-		(
-			await prisma.fleet_agent_runs.updateMany({
-				where: { created_at: { lt: cutoff } },
-				data: { transcript: Prisma.DbNull },
-			})
-		).count,
-};
-
-export async function pruneStaleData({
-	config,
-}: {
-	config: ScheduledJobConfig;
-}): Promise<void> {
-	const log = getAppLogger();
-	const retention = config.retention;
-	if (!retention || Object.keys(retention).length === 0) {
-		log.info("[db-prune-stale-data] no retention entries — nothing to prune");
-		return;
-	}
-	const prisma = getPrisma();
-	let ran = 0;
-	let skipped = 0;
-	for (const [key, rawValue] of Object.entries(retention)) {
-		const op = PRUNE_OPS[key];
-		if (!op) {
-			log.warn(
-				`[db-prune-stale-data] skipping "${key}" — not in the prune allowlist ` +
-					`(audit_trail is excluded by audit-trail-permanent; add the op explicitly to enable)`,
-			);
-			skipped++;
-			continue;
-		}
-		const match = DURATION_RE.exec(rawValue.trim());
-		if (!match) {
-			log.warn(
-				`[db-prune-stale-data] skipping "${key}" — value "${rawValue}" is not a duration (expected e.g. "1 day")`,
-			);
-			skipped++;
-			continue;
-		}
-		const cutoff = new Date(Date.now() - Number(match[1]) * UNIT_TO_MS[match[2]!]);
-		const affected = await op(prisma, cutoff);
-		log.info(
-			`[db-prune-stale-data] pruned "${key}" older than ${rawValue} — ${affected} row(s) affected`,
-		);
-		ran++;
-	}
-	log.info(`[db-prune-stale-data] complete — ${ran} op(s) ran, ${skipped} skipped`);
-}
-
-pgBossHandlerRegistry.register("@teamscala/service-boot:prune-stale-data", pruneStaleData);