@teamscala/service-boot 0.23.412 → 0.23.413

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.412",
+  "version": "0.23.413",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -170,6 +170,62 @@
       "types": "./src/build-client-assets/input-hashing.d.ts",
       "default": "./src/build-client-assets/input-hashing.ts"
     },
+    "./build-client-assets/input-fingerprint": {
+      "types": "./src/build-client-assets/input-fingerprint.d.ts",
+      "default": "./src/build-client-assets/input-fingerprint.ts"
+    },
+    "./build-client-assets/input-fingerprint.ts": {
+      "types": "./src/build-client-assets/input-fingerprint.d.ts",
+      "default": "./src/build-client-assets/input-fingerprint.ts"
+    },
+    "./build-client-assets/hashed-output": {
+      "types": "./src/build-client-assets/hashed-output.d.ts",
+      "default": "./src/build-client-assets/hashed-output.ts"
+    },
+    "./build-client-assets/hashed-output.ts": {
+      "types": "./src/build-client-assets/hashed-output.d.ts",
+      "default": "./src/build-client-assets/hashed-output.ts"
+    },
+    "./build-client-assets/hydrate-bundle": {
+      "types": "./src/build-client-assets/hydrate-bundle.d.ts",
+      "default": "./src/build-client-assets/hydrate-bundle.ts"
+    },
+    "./build-client-assets/hydrate-bundle.ts": {
+      "types": "./src/build-client-assets/hydrate-bundle.d.ts",
+      "default": "./src/build-client-assets/hydrate-bundle.ts"
+    },
+    "./build-client-assets/sourcemaps-upload": {
+      "types": "./src/build-client-assets/sourcemaps-upload.d.ts",
+      "default": "./src/build-client-assets/sourcemaps-upload.ts"
+    },
+    "./build-client-assets/sourcemaps-upload.ts": {
+      "types": "./src/build-client-assets/sourcemaps-upload.d.ts",
+      "default": "./src/build-client-assets/sourcemaps-upload.ts"
+    },
+    "./build-client-assets/styles-build": {
+      "types": "./src/build-client-assets/styles-build.d.ts",
+      "default": "./src/build-client-assets/styles-build.ts"
+    },
+    "./build-client-assets/styles-build.ts": {
+      "types": "./src/build-client-assets/styles-build.d.ts",
+      "default": "./src/build-client-assets/styles-build.ts"
+    },
+    "./build-client-assets/manifest": {
+      "types": "./src/build-client-assets/manifest.d.ts",
+      "default": "./src/build-client-assets/manifest.ts"
+    },
+    "./build-client-assets/manifest.ts": {
+      "types": "./src/build-client-assets/manifest.d.ts",
+      "default": "./src/build-client-assets/manifest.ts"
+    },
+    "./build-client-assets/build-lock": {
+      "types": "./src/build-client-assets/build-lock.d.ts",
+      "default": "./src/build-client-assets/build-lock.ts"
+    },
+    "./build-client-assets/build-lock.ts": {
+      "types": "./src/build-client-assets/build-lock.d.ts",
+      "default": "./src/build-client-assets/build-lock.ts"
+    },
     "./build-client-assets/source-candidates": {
       "types": "./src/build-client-assets/source-candidates.d.ts",
       "default": "./src/build-client-assets/source-candidates.ts"

package/src/build-client-assets/build-lock.ts

@@ -0,0 +1,55 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The host-wide client-build lock of the client-asset build: serialises the
+ * heavy boot-time client build across ALL kind:ui services
+ * (client-asset-builds-serialize-via-lock), with a DB-driven TTL that
+ * fail-softs to a hardcoded default.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
+ * else.
+ */
+
+import { join } from "node:path";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import { userHome } from "@teamscala/os/host-paths";
+import * as v from "valibot";
+
+// Single shared host lock serialising the heavy boot-time client build across
+// ALL kind:ui services (client-asset-builds-serialize-via-lock). A publish of a
+// widely-consumed package makes the dep-sync restart every consumer at
+// once; without this lock each one rebuilds its hydrate bundle + Tailwind CSS
+// simultaneously and N concurrent builds saturate the host (load 36, each ~15s
+// build starved to ~10min, services offline — 2026-06-13). The build sibling of
+// `restart-drivers-serialize-via-lock`'s `.scala-pm2-restart.lock`.
+const CLIENT_BUILD_LOCK = join(userHome(), ".scala-client-build.lock");
+// Generous: serialised builds drain well within this. On timeout we build
+// UNLOCKED (fail-open) — the lock is a thundering-herd optimisation, never a
+// correctness gate, and must never block a boot. TTL is DB-driven
+// (config/build-client-assets), promoted from the former hardcoded constant.
+const DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS = 600_000;
+let cachedClientBuildLockTimeoutMs: number | undefined;
+
+export async function getClientBuildLockTimeoutMs(): Promise<number> {
+	if (cachedClientBuildLockTimeoutMs !== undefined) return cachedClientBuildLockTimeoutMs;
+	// Fail-soft to the hardcoded default: the deploy-build bake runs this in a
+	// standalone subprocess with NO registered Prisma client (a pre-DB build
+	// context), so loadRegistryConfig throws "Prisma client not registered". The
+	// lock is a thundering-herd optimisation, never a correctness gate ("must
+	// never block a boot"), and the TTL has a safe hardcoded default — so a
+	// registry-read failure must degrade to the default, never abort the bake.
+	try {
+		const row = await loadRegistryConfig("config", "build-client-assets", v.looseObject({}));
+		cachedClientBuildLockTimeoutMs =
+			(row?.client_build_lock_timeout_ms as number | undefined) ??
+			DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS;
+	} catch {
+		cachedClientBuildLockTimeoutMs = DEFAULT_CLIENT_BUILD_LOCK_TIMEOUT_MS;
+	}
+	return cachedClientBuildLockTimeoutMs;
+}
+
+export { CLIENT_BUILD_LOCK };

package/src/build-client-assets/hashed-output.ts

@@ -0,0 +1,39 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Content-hashed output housekeeping for the client-asset build: the
+ * short content hash stamped into hashed filenames, and removal of stale
+ * hashed files from a previous build so dist/client/ never accumulates
+ * dead outputs.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent except createHash →
+ * Bun.CryptoHasher (bun-native-crypto guard; identical digest output).
+ */
+
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function fileHash(path: string): Promise<string> {
+	const buf = await Bun.file(path).text();
+	return new Bun.CryptoHasher("sha256").update(buf).digest("hex").slice(0, 10);
+}
+
+export async function removeStaleHashedFiles(
+	outDir: string,
+	base: string,
+	ext: string,
+	keep: string,
+): Promise<void> {
+	if (!(await Bun.file(outDir).exists())) return;
+	const re = new RegExp(`^${base}-[a-f0-9]+\\.${ext}$`);
+	for (const name of (await readdir(outDir, "utf-8"))) {
+		if (re.test(name) && name !== keep) {
+			try {
+				await rm(join(outDir, name));
+			} catch {}
+		}
+	}
+}

package/src/build-client-assets/hydrate-bundle.ts

@@ -0,0 +1,298 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The hydrate JS bundle unit of the client-asset build: Bun.build over
+ * src/entry-client.ts with the resilient-block-imports plugin (dead block
+ * imports degrade at runtime instead of crash-looping the service), the
+ * post-build dead-facade gate, stale-chunk removal, and source-map upload.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent — imports adjusted, nothing
+ * else.
+ */
+
+import { mkdir, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { fileHash, removeStaleHashedFiles } from "./hashed-output.ts";
+import { uploadSourceMaps } from "./sourcemaps-upload.ts";
+
+const HYDRATE_BASE = "hydrate";
+
+export async function buildHydrateBundle(
+	cwd: string,
+	log: ReturnType<typeof getAppLogger>,
+): Promise<string | null> {
+	const entry = join(cwd, "src", "entry-client.ts");
+	const outDir = join(cwd, "dist", "client");
+	const tmpFile = join(outDir, `${HYDRATE_BASE}.js`);
+
+	if (!(await Bun.file(entry).exists())) {
+		log.warn(
+			`[build-client-assets] src/entry-client.ts not found at ${entry} — skipping JS bundle`,
+		);
+		return null;
+	}
+
+	await mkdir(outDir, { recursive: true });
+
+	// Resilience (block-and-provider-error-isolation applied to the BUILD): a
+	// page-manifest.ts lazy import of a block whose component no longer resolves
+	// (a block_schema deactivation or a removed package export whose manifest
+	// regen never propagated) MUST NOT fail the whole bundle and crash-loop the
+	// service. Seven UI services went down at once this way on 2026-06-13. Such
+	// an import is EXTERNALIZED instead: the build succeeds, the service boots,
+	// and at runtime that one lazy import rejects into the block's
+	// BlockErrorBoundary — the dead block degrades, the page + service stay up.
+	// Only UNRESOLVABLE @teamgbg specifiers are touched (resolvable ones fall
+	// through to Bun's normal resolution unchanged). Surfaced via warn so it is
+	// never silent; the `no-dead-block-imports-in-manifest` guard still flags the
+	// stale manifest so it gets regenerated.
+	const externalizedBlocks: string[] = [];
+	const resilientBlockPlugin: Bun.BunPlugin = {
+		name: "resilient-block-imports",
+		setup(build: { onResolve: (opts: { filter: RegExp }, cb: (args: { path: string }) => { path: string; external: boolean } | undefined) => void }) {
+			// Externalize an unresolvable @teamscala/* block import (a deactivated
+			// block_schema whose manifest regen never propagated) or a broken
+			// third-party internal (@fullcalendar/core/internal.js during a version
+			// mismatch) so it degrades ONE block at runtime instead of crash-looping
+			// the service (2026-07-21 portal outage: @fullcalendar 7.x + plugins 6.x
+			// → unresolvable internal.js → 21 crash-loop restarts).
+			//
+			// The filter is deliberately NARROW — only the package prefixes where
+			// unresolvable imports actually occur — NOT every bare import. The prior
+			// broad /^(?![./])/ filter intercepted resolvable shared packages too,
+			// and onResolve pass-through (return undefined) on a shared
+			// sideEffects:false package (@tanstack/react-query, imported across many
+			// lazy block chunks) tripped Bun's code-splitter: it emitted a dead
+			// `export{...}`-with-no-`from` facade and tree-shook away the entire
+			// query-core implementation → a fatal hydration SyntaxError that froze
+			// agents.scala.business while every component reported healthy
+			// (2026-07-22; see the dead-facade gate + minifyIdentifiers:false
+			// below). Intercepts of node builtins (stream/web) likewise pulled them
+			// into the browser build. The narrow filter leaves @tanstack/* + builtins
+			// to Bun's native (correct) resolution. A future unresolvable import
+			// OUTSIDE these prefixes fails loud via the manifest guard + build
+			// tombstone (no-dead-block-imports-in-manifest) — never silent.
+			// Entry-point imports are excluded — those must fail loudly (silently
+			// externalizing a core import turns a build error into a mystery runtime
+			// crash; containment must not become a swallow).
+			build.onResolve({ filter: /^(@teamgbg\/|@fullcalendar\/)/ }, (args) => {
+				if (args.importer === entry) return undefined;
+				try {
+					Bun.resolveSync(args.path, cwd);
+					return undefined;
+				} catch {
+					if (!externalizedBlocks.includes(args.path)) externalizedBlocks.push(args.path);
+					return { path: args.path, external: true };
+				}
+			});
+		},
+	};
+
+	let result: Awaited<ReturnType<typeof Bun.build>>;
+	try {
+		result = await Bun.build({
+			entrypoints: [entry],
+			target: "browser",
+			outdir: outDir,
+			naming: `${HYDRATE_BASE}.js`,
+			// minifyIdentifiers is DISABLED (whitespace + syntax/dead-code minify
+			// kept): under code-splitting, identifier mangling interacting with a
+			// shared sideEffects:false package (@tanstack/react-query) trips Bun's
+			// splitter to tree-shake away the entire implementation and emit a dead
+			// re-export facade — a fatal hydration SyntaxError that froze
+			// agents.scala.business while every component reported healthy
+			// (2026-07-22; reproduces in stable 1.3.14 + canary 1.4.0, so an upstream
+			// fix is not near). Whitespace + syntax minify retain the bulk of the
+			// size win; only name-mangling is dropped. The post-build dead-facade
+			// gate below fails the build LOUD if this or any future regression slips
+			// a fatal facade through on any UI service.
+			minifyWhitespace: process.env.NODE_ENV === "production",
+			minifySyntax: process.env.NODE_ENV === "production",
+			minifyIdentifiers: false,
+			// Bun plugin type
+			plugins: [resilientBlockPlugin],
+			// Code-splitting honours `lazy-blocks-per-page`: page-manifest.ts wraps
+			// every block in `lazy(() => import())`, so splitting emits the heavy
+			// Plate editor + each lazy block as a SEPARATE chunk loaded on demand
+			// instead of inlining all of them into one ~12.5MB entry. The initial
+			// download drops ~10× (entry ~1.2MB; chunks lazy). splitting:false was
+			// drift that defeated the lazy manifest. SSR safety is intact — the
+			// page-server awaits stream.allReady before flushing (render-page-html),
+			// so every block is server-rendered and hydration is consistent.
+			splitting: true,
+			// External source maps so minified client stacks resolve to source in
+			// GlitchTip (uploaded post-build by uploadSourceMaps via the official
+			// glitchtip-cli debug-ID flow). Maps are deleted after upload — never
+			// served; the debug IDs injected into the bundles are all the SDK needs.
+			sourcemap: "external",
+			// Chunks are referenced by absolute /assets/ URL (served by
+			// register-static-assets' /assets/* handler), never a relative path that
+			// could mis-resolve under a record route like /?id=<uuid>.
+			publicPath: "/assets/",
+			external: ["*.css"],
+		});
+	} catch (e) {
+		// Bun.build can THROW (not return {success:false}) on certain failure
+		// modes — e.g. entrypoint resolves to a path Bun can't read, or an
+		// internal panic. Without this catch the boot path swallows the
+		// useful diagnostic and the operator sees only "Bundle failed".
+		// AggregateError carries the per-file resolution list in .errors —
+		// without serializing it the operator sees only "Bundle failed"
+		// (cost a full Railway round-trip per guess on 2026-06-05).
+		const subErrors =
+			e instanceof AggregateError
+				? e.errors.map((se) => (se instanceof Error ? se.message : String(se)))
+				: [];
+		log.error(`[build-client-assets] Bun.build threw`, {
+			message: e instanceof Error ? e.message : String(e),
+			errors: subErrors,
+			stack: e instanceof Error ? e.stack : undefined,
+			entry,
+			outDir,
+		});
+		throw new Error(
+			`[build-client-assets] Bun.build threw: ${e instanceof Error ? e.message : String(e)}${subErrors.length ? `\n${subErrors.join("\n")}` : ""}`,
+		);
+	}
+
+	if (!result.success) {
+		// Bun.build's `.logs` is the verbose-build-message list. Each log is an
+		// object with at minimum `{ level, message, position }`. Some failures
+		// surface with an empty logs array — happens when Bun bails before
+		// resolution (e.g. missing entrypoint after symlink-walk). Always emit
+		// the full JSON form via the logger so service-runtime's structured
+		// error trail captures every field, not just a `.message`-joined string.
+		log.error(`[build-client-assets] Bun.build failed`, {
+			logs: result.logs.map((l) => ({
+				level: (l as { level?: string }).level,
+				message: l.message,
+				position: (l as { position?: unknown }).position,
+			})),
+			outputs: result.outputs.length,
+			entry,
+			outDir,
+		});
+		const messages = result.logs.length
+			? result.logs
+					.map(
+						(l) => `[${(l as { level?: string }).level ?? "?"}] ${l.message}`,
+					)
+					.join("\n")
+			: "(no log entries — likely entrypoint resolution failure)";
+		throw new Error(`[build-client-assets] Bun.build failed:\n${messages}`);
+	}
+
+	// dead-facade prevention gate (agents.scala.business 2026-07-22): a Bun
+	// splitter+tree-shake bug (stable 1.3.14 + canary 1.4.0) can emit a "dead
+	// facade" chunk — `export { ... }` with NO `from` clause and NO local binding
+	// definitions — a fatal SyntaxError at module load that kills React hydration
+	// SILENTLY (the whole dashboard froze while every component reported healthy).
+	// The narrow resilientBlockPlugin filter + minifyIdentifiers:false above
+	// prevent the known trigger (@tanstack/react-query under split); this gate
+	// makes the CLASS unshippable — any dead facade from ANY package on ANY UI
+	// service fails the build LOUD here instead of freezing the page. Detection
+	// is POSITION-INDEPENDENT — a named export{} ANYWHERE in the comment-stripped
+	// body, with no `from` clause and no local declaration/import backing the
+	// names, is the facade (Bun could prefix it with a directive or statement, not
+	// only emit it at the very start — a positional assumption is a known way to
+	// be silently bypassed; a valid local-export chunk carries a
+	// class/function/const/var/let/import, a valid re-export carries `from`).
+	const deadFacades: string[] = [];
+	for (const out of result.outputs) {
+		if (out.kind !== "chunk") continue;
+		let text: string;
+		try {
+			text = await Bun.file(out.path).text();
+		} catch {
+			continue;
+		}
+		const stripped = text
+			.replace(/\/\/#.*$/gms, "")
+			.replace(/\/\/[^\n]*/g, "")
+			.replace(/\/\*[\s\S]*?\*\//g, "")
+			.trim();
+		if (
+			/export\s*\{[^}]*\}/.test(stripped) &&
+			!/\bfrom\s*["']/.test(stripped) &&
+			!/\b(?:class|function|const|var|let|import)\b/.test(stripped)
+		) {
+			deadFacades.push(out.path.split("/").pop() ?? out.path);
+		}
+	}
+	if (deadFacades.length > 0) {
+		log.error(`[build-client-assets] dead-facade gate: refusing to ship fatal bundle`, {
+			deadFacades,
+			hint: "A dead facade (export{} with no from/source) is a fatal hydration SyntaxError. Investigate a shared sideEffects:false package under splitting, or a Bun splitter+minifyIdentifiers regression.",
+		});
+		throw new Error(
+			`[build-client-assets] Bun.build emitted ${deadFacades.length} dead facade chunk(s) (export{} with no from/source — a fatal hydration SyntaxError). Refusing to ship a broken bundle. Files: ${deadFacades.join(", ")}`,
+		);
+	}
+
+	const hash = await fileHash(tmpFile);
+	const hashedName = `${HYDRATE_BASE}-${hash}.js`;
+	const hashedPath = join(outDir, hashedName);
+	await rename(tmpFile, hashedPath);
+	removeStaleHashedFiles(outDir, HYDRATE_BASE, "js", hashedName);
+
+	// Splitting emits one chunk per lazy import() alongside the entry. Keep the
+	// chunks THIS build produced; drop stale ones so dist/client/ doesn't
+	// accumulate hundreds of orphaned chunks per rebuild.
+	const currentChunks = new Set(
+		result.outputs
+			.filter((o) => o.kind === "chunk")
+			.map((o) => o.path.split("/").pop() as string),
+	);
+	await removeStaleChunks(outDir, currentChunks);
+
+	// Bundle telemetry → logger (single-logger-entry-point → GlitchTip): the
+	// initial-download size + lazy-chunk footprint are visible per build, so a
+	// regression (splitting silently off, or a heavy dep landing in the entry)
+	// surfaces as a number instead of a mystery "slow page".
+	const entryBytes = (await Bun.file(hashedPath).stat()).size;
+	let chunkBytes = 0;
+	for (const name of currentChunks) {
+		try {
+			chunkBytes += (await Bun.file(join(outDir, name)).stat()).size;
+		} catch {}
+	}
+	log.info(
+		`[build-client-assets] hydrate built → ${hashedName} (entry ${(entryBytes / 1024).toFixed(0)}KB + ${currentChunks.size} lazy chunks ${(chunkBytes / 1048576).toFixed(1)}MB)`,
+		{ entryBytes, chunkCount: currentChunks.size, chunkBytes },
+	);
+	if (externalizedBlocks.length > 0) {
+		// The service boots; these blocks degrade at runtime (BlockErrorBoundary)
+		// instead of crash-looping the whole service. The stale manifest still
+		// needs regenerating — surfaced here AND by no-dead-block-imports-in-manifest.
+		log.warn(
+			`[build-client-assets] ${externalizedBlocks.length} unresolvable block import(s) externalized (degraded, not fatal) — regenerate this service's page-manifest: ${externalizedBlocks.join(", ")}`,
+			{ externalizedBlocks },
+		);
+	}
+	// Upload source maps to GlitchTip (best-effort, dev-host-only) + delete the
+	// .map files so source never ships publicly. See uploadSourceMaps.
+	await uploadSourceMaps(outDir, hash, log);
+	return `/assets/${hashedName}`;
+}
+
+// Remove hashed code-split chunks no longer referenced by the current entry.
+// Keyed off the build's own output list (the only authoritative current set),
+// never a name pattern guess — a build emits N `chunk-*.js`; the previous
+// build's are orphaned the moment the entry's hash changes.
+async function removeStaleChunks(
+	outDir: string,
+	keep: Set<string>,
+): Promise<void> {
+	if (!(await Bun.file(outDir).exists())) return;
+	for (const name of (await readdir(outDir, "utf-8"))) {
+		if (/^chunk-[A-Za-z0-9]+\.js$/.test(name) && !keep.has(name)) {
+			try {
+				await rm(join(outDir, name));
+			} catch {}
+		}
+	}
+}

package/src/build-client-assets/input-fingerprint.ts

@@ -0,0 +1,108 @@
+/**
+ * @system server-handlers
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The content fingerprint of the client-bundle dependency closure — the
+ * cache key that decides whether the boot-time client-asset build can be
+ * skipped. Composes the input-hashing module's closure walkers.
+ *
+ * Split out of build-client-assets.ts (962 lines) alongside its build
+ * siblings. Byte-for-byte move from the parent except createHash →
+ * Bun.CryptoHasher (bun-native-crypto guard; identical digest output).
+ */
+
+import { join } from "node:path";
+import {
+	hashResolvedPackageStylesheets,
+	hashTeamgbgJsGraph,
+} from "./input-hashing.ts";
+
+// Content fingerprint of the client-bundle dependency CLOSURE — hashed by
+// CONTENT, never mtime (cache-key-hashes-source-inputs-only). Rebuild iff this
+// differs from the fingerprint stored in the existing manifest. Scoped to the
+// CLOSURE (not all of node_modules) so a @teamscala/* publish that is not in this
+// service's client bundle cannot trigger a rebuild — the publish→rebuild storm
+// is architecturally impossible (`no-uncontrolled-repetition-or-cascade`).
+//
+// Inputs (everything that can change the emitted bytes):
+//   src/entry-client.ts — the bundle entrypoint.
+//   src/page-manifest.ts — the generated block→component map the bundle is built
+//                       from; a codegen regen (block added/removed) changes it,
+//                       and the hydrate bundle MUST rebuild or new blocks render
+//                       empty → hydration mismatch.
+//   src/app.css        — the Tailwind entry.
+//   @teamscala/* JS closure (hashTeamgbjJsGraph) — the CONTENT of every @teamscala/*
+//                       module reachable from the client entrypoints. Content
+//                       (not version) so a mid-install stale bake (bun.lock
+//                       ahead of node_modules — the lock can name a new version
+//                       while the prior bytes are still on disk) is detected on
+//                       the next boot and self-heals (scala-agents 2026-07-12).
+//   @teamscala/* CSS closure (hashResolvedPackageStylesheets) — the CONTENT of
+//                       every package stylesheet app.css @imports (transitively).
+//   third-party closure-boundary versions (hashTeamgbgJsGraph) — the resolved
+//                       VERSION of each third-party package the client closure
+//                       imports (react, etc.). Third-party modules are not
+//                       content-walked (large; pinned by bun.lock + change only
+//                       on a version bump), but a version bump of a closure dep
+//                       MUST invalidate, so the installed package.json#version
+//                       is folded. This is the closure-scoped replacement for
+//                       hashing all of bun.lock: react bumping in the closure
+//                       still rebuilds, while a backend @teamscala/* publish
+//                       outside the closure does not.
+// NB: bun.lock is INTENTIONALLY NOT an input. It encodes every resolved
+//    @teamscala/* version (backend packages included), so it invalidates on every
+//    publish — the false-invalidation source that made every UI service rebuild
+//    on a backend publish. The closure inputs above are a strict improvement:
+//    they catch every change that affects THIS bundle AND nothing that doesn't.
+export async function computeInputFingerprint(cwd: string): Promise<string> {
+	// Keyed on each input's RELATIVE label + CONTENT only — never the absolute
+	// path (that would make the fingerprint cwd-dependent and defeat the skip
+	// across two checkouts of the same service). bun.lock is DELIBERATELY
+	// EXCLUDED — it encodes EVERY resolved @teamscala/* version, so folding it in
+	// invalidates on every publish including packages NOT in this service's
+	// client bundle (the publish→rebuild storm — `no-uncontrolled-repetition-
+	// or-cascade`). The closure content hashes below (hashTeamgbgJsGraph +
+	// hashResolvedPackageStylesheets) + the third-party closure-boundary
+	// versions cover every dependency change that ACTUALLY affects this bundle,
+	// so a non-closure publish changes nothing here → zero rebuild. Rebuild
+	// iff this fingerprint differs from the one stored in the manifest.
+	const sources: Array<[label: string, path: string]> = [
+		["src/entry-client.ts", join(cwd, "src", "entry-client.ts")],
+		["src/page-manifest.ts", join(cwd, "src", "page-manifest.ts")],
+		["src/app.css", join(cwd, "src", "app.css")],
+	];
+	const h = new Bun.CryptoHasher("sha256");
+	for (const [label, path] of sources) {
+		// Missing input contributes a stable sentinel rather than throwing — a
+		// backend service has no app.css, and that absence is itself part of the
+		// fingerprint. `(await Bun.file().text())` is parenthesised so a missing
+		// file's sync TypeError is caught (bun-async-file-operations).
+		try {
+			h.update(label).update("\0").update(await Bun.file(path).text()).update("\0");
+		} catch {
+			h.update(label).update("\0<absent>\0");
+		}
+	}
+	// Fold the resolved CONTENT of every @teamscala/* stylesheet app.css @imports
+	// (client-asset-cache-key-embeds-package-content). bun.lock pins versions; the
+	// build reads bytes. When they diverge (boot built mid-install), the lock-only
+	// fingerprint false-matches and skips forever — hashing the bytes closes it.
+	await hashResolvedPackageStylesheets(cwd, h);
+	// Fold in the resolved CONTENT of every @teamscala/* JS/TS module reachable
+	// from the client entrypoints (hashTeamgbgJsGraph). bun.lock pins versions;
+	// the build reads BYTES — and a boot can build MID-INSTALL (the package-
+	// poller restarts the service after writing the new bun.lock but before
+	// node_modules extraction finishes), so Bun.build faithfully bakes the OLD
+	// @teamgbg JS while the lock-derived fingerprint is stored as "current".
+	// Every later restart then recomputes the same lock fingerprint → skip →
+	// STALE bundle served forever (scala-agents 2026-07-12: hydrate-4dad7478bd
+	// carried zero of portal-ui@2.4.41's markers across restarts). Bun.build
+	// itself is NOT caching — an isolated repro proves it reads fresh content
+	// across processes — so the fix is to make the fingerprint cover the actual
+	// @teamgbg JS bytes (the JS analogue of hashResolvedPackageStylesheets,
+	// which already closes this exact race for CSS). A stale bake then hashes
+	// differently from the freshly-installed bytes → rebuild → self-heals.
+	await hashTeamgbgJsGraph(cwd, h);
+	return h.digest("hex").slice(0, 16);
+}