@teamscala/service-boot 0.23.430 → 0.23.432

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

@@ -12,50 +12,28 @@
  * 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`).
+// 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> {
+// 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.
+
+// Why: Content fingerprint of the client-bundle dependency CLOSURE …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 	// 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
@@ -67,6 +45,35 @@ export async function computeInputFingerprint(cwd: string): Promise<string> {
 	// 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.
+
+// Why: Keyed on each input's RELATIVE label + CONTENT only — never …
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+	// 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.
+
+// Why: Fold in the resolved CONTENT of every @teamscala/* JS/TS mod…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { join } from "node:path";
+import {
+	hashResolvedPackageStylesheets,
+	hashTeamgbgJsGraph,
+} from "./input-hashing.ts";
+
+export async function computeInputFingerprint(cwd: string): Promise<string> {
 	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")],
@@ -89,20 +96,6 @@ export async function computeInputFingerprint(cwd: string): Promise<string> {
 	// 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);
 }

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

@@ -66,10 +66,8 @@ export async function hashResolvedPackageStylesheets(
 	}
 }
 
-// The JS twin of hashResolvedPackageStylesheets: resolve + hash the CONTENT of
-// every @teamscala/* JS/TS module reachable from the client entrypoints, so a
-// mid-install stale bake (bun.lock ahead of node_modules — see computeInputFingerprint)
-// is detected on the next boot and self-heals. Third-party modules are NOT walked
+// The JS twin of hashResolvedPackageStylesheets: resolve + hash the CONTENT of every @teamscala/* JS/TS module reachable from the client entrypoints, so a
+// mid-install stale bake (bun.lock ahead of node_modules — see computeInputFingerprint) is detected on the next boot and self-heals. Third-party modules are NOT walked
 // (their versions are pinned by bun.lock and they don't change on a @teamgbg
 // publish); only the @teamgbg surface — the publish-driven change graph — is folded.
 //

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

@@ -21,16 +21,11 @@ export const MANIFEST_FILE = "asset-manifest.json";
 export interface AssetManifest {
 	stylesPath: string;
 	hydratePath: string;
-	// Content fingerprint of the CLIENT-BUNDLE DEPENDENCY CLOSURE (source
-	// entrypoints + @teamscala/* JS/CSS in the closure + third-party closure-dep
-	// versions), hashed by CONTENT — never mtime (cache-key-hashes-source-
-	// inputs-only). The boot/build freshness check rebuilds iff this differs
-	// from the current closure. mtime comparison is fundamentally broken on
-	// Railway: deploy-build bakes the bundle at image-build time, and under the
-	// hoisted linker + warm `bun-install` cache the installed @teamscala/* files
-	// are hardlinks carrying OLD extraction mtimes while the baked manifest's
-	// mtime is newer — so `source.mtime > manifest.mtime` is false and the
-	// build wrongly skips, baking (then serving forever) a STALE client bundle
+	// Content fingerprint of the CLIENT-BUNDLE DEPENDENCY CLOSURE (source entrypoints + @teamscala/* JS/CSS in the closure + third-party closure-dep
+	// versions), hashed by CONTENT — never mtime (cache-key-hashes-source- inputs-only). The boot/build freshness check rebuilds iff this differs
+	// from the current closure. mtime comparison is fundamentally broken on Railway: deploy-build bakes the bundle at image-build time, and under the
+	// hoisted linker + warm `bun-install` cache the installed @teamscala/* files are hardlinks carrying OLD extraction mtimes while the baked manifest's
+	// mtime is newer — so `source.mtime > manifest.mtime` is false and the build wrongly skips, baking (then serving forever) a STALE client bundle
 	// even though a newer @teamscala/* version is installed. Observed 2026-06-14:
 	// scala-gpt shipped ui-foundation < 85 in the bundle while a newer version
 	// was installed, so a published+installed fix never reached the browser.
@@ -79,7 +74,9 @@ export async function readClientBuildStatus(
 				at: parsed.buildFailedAt,
 			};
 		}
-	} catch {}
+	} catch (error) {
+		log.warn("asset manifest unreadable — reporting not-failed", error);
+	}
 	return { failed: false };
 }
 

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

@@ -20,23 +20,15 @@
  * Byte-for-byte move — imports adjusted, nothing else.
  */
 
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 
-// Tailwind v4's low-level `compile()` does NOT scan content — `compiler.build(
-// candidates)` only emits utilities for the candidate class names it is GIVEN.
-// `build([])` therefore emits ZERO content-driven utilities (only the static
-// theme/base + @utility/@layer + imported package CSS). The workspace's own
-// blocks mostly use inline styles + hand-written `blk-*` package classes
-// (no-tailwind-in-blocks / layout-properties-inline), so the missing utility
-// layer was invisible — until the Plate document editor (third-party shadcn
-// components using raw `flex`/`p-1`/`bg-background/95`) rendered completely
-// unstyled (operator's tablet, 2026-06-13). The CLI we replaced
-// (`b29e369` "in-process Bun compile") scanned content; the replacement dropped
-// the scan. This restores it: glob every resolved `@source` dir, extract
-// candidate tokens, and feed them to `build()`. @tailwindcss/oxide's native
+// Tailwind v4's low-level `compile()` does NOT scan content — `compiler.build( candidates)` only emits utilities for the candidate class names it is GIVEN.
+// `build([])` therefore emits ZERO content-driven utilities (only the static theme/base + @utility/@layer + imported package CSS). The workspace's own
+// blocks mostly use inline styles + hand-written `blk-*` package classes (no-tailwind-in-blocks / layout-properties-inline), so the missing utility
+// layer was invisible — until the Plate document editor (third-party shadcn components using raw `flex`/`p-1`/`bg-background/95`) rendered completely
+// unstyled (operator's tablet, 2026-06-13). The CLI we replaced (`b29e369` "in-process Bun compile") scanned content; the replacement dropped
+// the scan. This restores it: glob every resolved `@source` dir, extract candidate tokens, and feed them to `build()`. @tailwindcss/oxide's native
 // Scanner is NOT a dependency of the bare `tailwindcss` lib (only of the
 // integration packages), so we tokenize ourselves — over-extraction is safe
 // (build() ignores any token that isn't a valid utility). Enforced by
@@ -75,7 +67,7 @@ export async function scanSourceCandidates(
 		// that package resolves to a non-existent dir. Skip silently rather than
 		// warn on every UI-service boot (the log-flood class — the ENOENT whose
 		// path rendered with a trailing null byte). Real errors below still warn.
-		if (!existsSync(root)) continue;
+		if (!await Bun.file(root).exists()) continue;
 		// A root INSIDE node_modules is an explicit `@source` into an installed
 		// block package (the app-css transform emits one per package) — scan it
 		// fully. A root OUTSIDE node_modules is the service's own tree — scan it
@@ -94,7 +86,7 @@ export async function scanSourceCandidates(
 				if (dot < 0 || !SCAN_EXTS.has(file.slice(dot))) continue;
 				let text: string;
 				try {
-					text = await readFile(file, "utf-8");
+					text = await Bun.file(file).text();
 				} catch {
 					continue;
 				}

package/src/build-client-assets/sourcemaps-upload.ts

@@ -11,13 +11,6 @@
  * else.
  */
 
-import { existsSync } from "node:fs";
-import { readdir, rm } from "node:fs/promises";
-import { join } from "node:path";
-import { getAppLogger } from "@teamscala/logger/app-loggers";
-import { userHome } from "@teamscala/os/host-paths";
-import { spawnSync } from "@teamscala/os/spawn";
-
 /**
  * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
  * flow (the documented first-class mechanism — `sourcemaps inject` then
@@ -29,6 +22,16 @@ import { spawnSync } from "@teamscala/os/spawn";
  * maps are a follow-up). The .map files are deleted after upload — source never
  * ships publicly; the debug IDs in the served bundles are all the SDK needs.
  */
+
+// Why: Upload source maps to GlitchTip via the official `glitchtip-…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { userHome } from "@teamscala/os/host-paths";
+import { spawnSync } from "@teamscala/os/spawn";
+
 export async function uploadSourceMaps(
 	outDir: string,
 	release: string,
@@ -44,7 +47,7 @@ export async function uploadSourceMaps(
 	try {
 		// Inject debug IDs into the bundles + maps (if glitchtip-cli is present).
 		// The CLI is optional — only used for the inject step.
-		if (existsSync(cli)) {
+		if (await Bun.file(cli).exists()) {
 			spawnSync({
 				name: "glitchtip-cli-sourcemaps-inject",
 				command: [cli, "sourcemaps", "inject", outDir],
@@ -76,7 +79,9 @@ export async function uploadSourceMaps(
 					{ method: "POST", headers, body: form },
 				);
 				if (res.ok) uploaded++;
-			} catch {}
+			} catch (error) {
+				log.warn("sourcemap upload failed — remaining maps continue", error);
+			}
 		}
 		log.info("[build-client-assets] source maps uploaded to GlitchTip", {
 			release,
@@ -95,7 +100,9 @@ export async function uploadSourceMaps(
 		if (name.endsWith(".map")) {
 			try {
 				await rm(join(outDir, name));
-			} catch {}
+			} catch (error) {
+				getAppLogger().warn("sourcemaps-upload.ts: bare catch around upstream call — logged, continuing (protective-layers-fail-explicitly)", error);
+			}
 		}
 	}
 }

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

@@ -13,7 +13,6 @@
  * else.
  */
 
-import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { compile } from "tailwindcss";
@@ -30,32 +29,34 @@ async function resolveStylesheetRaw(
 ): Promise<{ path: string; base: string; content: string }> {
 	if (id === "tailwindcss") {
 		const r = await Bun.resolve("tailwindcss/index.css", cwd);
-		return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
+		return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 	}
 	try {
 		const r = await Bun.resolve(id, base);
-		return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
-	} catch {}
+		return { path: r, base: dirname(r), content: await Bun.file(r).text() };
+	} catch (error) {
+		log.warn("style import resolve failed — trying package fallback", error);
+	}
 	if (!id.startsWith(".")) {
 		try {
 			const pkgPath = await Bun.resolve(id + "/package.json", cwd);
-			const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+			const pkg = JSON.parse(await Bun.file(pkgPath).text());
 			const entry =
 				pkg.exports?.["."]?.style || pkg.style || pkg.main;
 			if (entry) {
 				const r = resolve(dirname(pkgPath), entry);
-				return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
+				return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 			}
-		} catch {}
+		} catch (error) {
+			log.warn("package style entry resolve failed — falling back to bare resolve", error);
+		}
 	}
 	const r = resolve(base, id);
-	return { path: r, base: dirname(r), content: await readFile(r, "utf-8") };
+	return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 }
 
-// Tailwind v4's compile() invokes `loadStylesheet` for DIRECT @imports in the
-// entry (app.css) but does NOT re-invoke it for @imports WITHIN the loaded
-// content — so a package styles.css that itself `@import "./Leaf.css"` (a
-// nested RELATIVE import) has its leaf silently dropped from the prod bundle.
+// Tailwind v4's compile() invokes `loadStylesheet` for DIRECT @imports in the entry (app.css) but does NOT re-invoke it for @imports WITHIN the loaded
+// content — so a package styles.css that itself `@import "./Leaf.css"` (a nested RELATIVE import) has its leaf silently dropped from the prod bundle.
 // This dropped every block-specific class reachable only via a nested
 // relative @import (project-list-view/ProjectListView.css's
 // .nested-list-table-host, audit-block's nested css, etc.) while direct
@@ -107,12 +108,9 @@ async function bunResolveStylesheet(
 	return { ...resolved, content };
 }
 
-// The app owns its fonts via an explicit, CSP-allowlisted <link> in index.html
-// (Google Fonts — `style-src ... fonts.googleapis.com`, `font-src ...
-// fonts.gstatic.com`). Third-party package CSS MUST NOT inject its own remote
-// `@import url(http…)`: @puckeditor/core/dist/index.css opens with
-// `@import "https://rsms.me/inter/inter.css"`, an arbitrary CDN our CSP does
-// NOT allow. The Tailwind compile inlines that mid-output, where it was either
+// The app owns its fonts via an explicit, CSP-allowlisted <link> in index.html (Google Fonts — `style-src ... fonts.googleapis.com`, `font-src ...
+// fonts.gstatic.com`). Third-party package CSS MUST NOT inject its own remote `@import url(http…)`: @puckeditor/core/dist/index.css opens with
+// `@import "https://rsms.me/inter/inter.css"`, an arbitrary CDN our CSP does NOT allow. The Tailwind compile inlines that mid-output, where it was either
 // silently dropped (CSS spec: @import must precede all rules) OR — once hoisted —
 // blocked by CSP, leaving a console error on every page; either way the font
 // never loaded and the site fell back to a system font (scala-docs 2026-06-13).
@@ -145,7 +143,7 @@ export async function buildTailwindCss(
 
 	await mkdir(outDir, { recursive: true });
 
-	const cssSource = await readFile(entry, "utf-8");
+	const cssSource = await Bun.file(entry).text();
 	const compiler = await compile(cssSource, {
 		base: cwd,
 		async loadStylesheet(id, base) {

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

@@ -11,7 +11,7 @@
  * CSP-allowlisted Google Fonts <link> in index.html instead.
  */
 
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, mkdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, describe, expect, test } from "bun:test";
@@ -66,7 +66,7 @@ describe("computeInputFingerprint", () => {
 		await mkdir(join(dir, "src"), { recursive: true });
 		for (const [rel, content] of Object.entries(files)) {
 			await mkdir(dirname(join(dir, rel)), { recursive: true });
-			await writeFile(join(dir, rel), content);
+			await Bun.file(join(dir, rel)).write(content);
 		}
 		return dir;
 	}

package/src/build-client-assets.ts

@@ -39,6 +39,22 @@
  * — split when the parent held them all at 962 lines.
  */
 
+	// Each build is wrapped in its own catch so a JS bundle failure (e.g. transient cross-package export drift) doesn't take down the service
+	// boot — SSR can still serve HTML; only client interactivity degrades. No fallback path for failed bundle builds — per `no-shims`, never write a
+	// manifest entry that points at a file we don't actually serve. If a build fails, write a TOMBSTONE manifest (no-silent-reverts) and throw.
+	//
+	// The tombstone preserves the LAST-SUCCESSFUL paths so SSR can keep serving the old bundle (better than a 404 hydrate), but marks itself
+	// `buildFailed: true` + the error + `failedAt`, AND sets `inputFingerprint` to a FAILURE sentinel so the next boot's "manifest up-to-date (skip)"
+	// check CANNOT match — the next boot is forced to retry the build explicitly (no silent skip on the stale manifest). The tombstone is the
+	// on-disk failure signal; ui-service-boot adds the runtime signal (recordEvent → event-log → GlitchTip) and read-html-template stamps the
+	// served HTML with the failure status. Without the tombstone, a build failure left the OLD manifest untouched and the dashboard served stale
+	// code with NO signal that the published fix never reached the bundle (scala-agents 2026-07-18: ui-foundation@3.4.5 installed but the bundle
+	// kept serving the old bytes across restarts while node_modules was mid-install — invisible until the operator hit the white-on-white
+	// toolbar regression the fix was supposed to close).
+
+// Why: Each build is wrapped in its own catch so a JS bundle failur…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { withFileLock } from "@teamscala/file-lock/with-lock";
@@ -105,28 +121,6 @@ async function performBuild(
 ): Promise<void> {
 	const t0 = Date.now();
 
-	// Each build is wrapped in its own catch so a JS bundle failure (e.g.
-	// transient cross-package export drift) doesn't take down the service
-	// boot — SSR can still serve HTML; only client interactivity degrades.
-	// No fallback path for failed bundle builds — per `no-shims`, never write a
-	// manifest entry that points at a file we don't actually serve. If a build
-	// fails, write a TOMBSTONE manifest (no-silent-reverts) and throw.
-	//
-	// The tombstone preserves the LAST-SUCCESSFUL paths so SSR can keep serving
-	// the old bundle (better than a 404 hydrate), but marks itself
-	// `buildFailed: true` + the error + `failedAt`, AND sets `inputFingerprint`
-	// to a FAILURE sentinel so the next boot's "manifest up-to-date (skip)"
-	// check CANNOT match — the next boot is forced to retry the build
-	// explicitly (no silent skip on the stale manifest). The tombstone is the
-	// on-disk failure signal; ui-service-boot adds the runtime signal
-	// (recordEvent → event-log → GlitchTip) and read-html-template stamps the
-	// served HTML with the failure status. Without the tombstone, a build
-	// failure left the OLD manifest untouched and the dashboard served stale
-	// code with NO signal that the published fix never reached the bundle
-	// (scala-agents 2026-07-18: ui-foundation@3.4.5 installed but the bundle
-	// kept serving the old bytes across restarts while node_modules was
-	// mid-install — invisible until the operator hit the white-on-white
-	// toolbar regression the fix was supposed to close).
 	const existingManifest = await readManifest(outDir);
 	const writeTombstone = async (reason: string): Promise<void> => {
 		try {

package/src/content-gate/access.ts

@@ -37,6 +37,7 @@ export async function attachContentGateAccess(
 		let resourceId = "";
 		let email = "";
 		let name = "";
+		let bodyFailed = false;
 		try {
 			const form = await c.req.parseBody();
 			resourceId = String(form[config.recordIdField] ?? "").trim();
@@ -44,9 +45,11 @@ export async function attachContentGateAccess(
 			// Optional captured display name (open-capture gates carry it in the
 			// token; allow-list gates ignore it via signToken).
 			name = String(form.name ?? "").trim();
-		} catch {
-			return c.redirect(back, 302);
+		} catch (error) {
+			log.warn(`[content-gate:${config.cookieName}] body parse failed — redirecting back: ${String(error)}`);
+			bodyFailed = true;
 		}
+		if (bodyFailed) return c.redirect(back, 302);
 		if (!resourceId || !email) return c.redirect(back, 302);
 
 		let matched = false;

package/src/content-gate/catalog.ts

@@ -26,19 +26,6 @@
  * will select from — not a step on the way to it.
  */
 
-import type { AccessConfig, ContentGateConfig } from "./config-types.ts";
-import { agreementAccessConfig, agreementGateConfig } from "../agreement-gate.ts";
-import { gptAccessConfig, gptGateConfig } from "../gpt-gate.ts";
-import { proposalAccessConfig, proposalGateConfig } from "../proposal-gate.ts";
-
-/** One gated content type: its SSR gate and its public access endpoint. */
-export interface ContentGateEntry {
-	/** Stable identity for this gate — what a `page_route` will name to select it. */
-	slug: string;
-	gate: ContentGateConfig;
-	access: AccessConfig;
-}
-
 /**
  * Registered gates, in evaluation order.
  *
@@ -51,12 +38,10 @@ export interface ContentGateEntry {
  * its kind — so listing a gate here never makes it apply to a page it does not
  * govern.
  */
-export const CONTENT_GATES: readonly ContentGateEntry[] = [
-	{ slug: "proposal", gate: proposalGateConfig, access: proposalAccessConfig },
-	{ slug: "agreement", gate: agreementGateConfig, access: agreementAccessConfig },
-	{ slug: "gpt", gate: gptGateConfig, access: gptAccessConfig },
-];
 
+// Why: Registered gates, in evaluation order.
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * Does this gate WITHHOLD content, or only identify the visitor?
  *
@@ -71,6 +56,29 @@ export const CONTENT_GATES: readonly ContentGateEntry[] = [
  * "governing" this page, or an anonymous visitor to a public GPT page would be
  * read as an unauthorized viewer and lose an assistant they are entitled to.
  */
+
+// Why: Does this gate WITHHOLD content, or only identify the visito…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import type { AccessConfig, ContentGateConfig } from "./config-types.ts";
+import { agreementAccessConfig, agreementGateConfig } from "../agreement-gate.ts";
+import { gptAccessConfig, gptGateConfig } from "../gpt-gate.ts";
+import { proposalAccessConfig, proposalGateConfig } from "../proposal-gate.ts";
+
+/** One gated content type: its SSR gate and its public access endpoint. */
+export interface ContentGateEntry {
+	/** Stable identity for this gate — what a `page_route` will name to select it. */
+	slug: string;
+	gate: ContentGateConfig;
+	access: AccessConfig;
+}
+
+export const CONTENT_GATES: readonly ContentGateEntry[] = [
+	{ slug: "proposal", gate: proposalGateConfig, access: proposalAccessConfig },
+	{ slug: "agreement", gate: agreementGateConfig, access: agreementAccessConfig },
+	{ slug: "gpt", gate: gptGateConfig, access: gptAccessConfig },
+];
+
 export function withholdsContent(entry: ContentGateEntry): boolean {
 	return entry.access.openCapture !== true;
 }

package/src/content-gate/gate.ts

@@ -10,9 +10,6 @@
  * functions. The single place that decides whether gated bytes reach the HTML.
  */
 
-import type { ContentGateConfig } from "./config-types.ts";
-import { parseCookie } from "./parse-cookie.ts";
-
 /**
  * What a gate decided, so a caller can act on it without re-deriving it.
  *
@@ -27,6 +24,13 @@ import { parseCookie } from "./parse-cookie.ts";
  * page), which is different from an unauthorized viewer and must not be
  * confused with one.
  */
+
+// Why: What a gate decided, so a caller can act on it without re-de…
+// (full note hoisted to this file's leading header — kept out of the body per
+// no-inline-prose-blocks / prose-stays-in-docs)
+import type { ContentGateConfig } from "./config-types.ts";
+import { parseCookie } from "./parse-cookie.ts";
+
 export interface ContentGateOutcome {
 	applies: boolean;
 	authorized: boolean;

package/src/discover-blocks.ts

@@ -20,6 +20,7 @@
  * no fallback to a package-side puckBlocks scan, which masked blockless boots.
  */
 
+import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { getPrisma } from "@teamscala/db/prisma-registry";
@@ -43,12 +44,9 @@ interface BlockSchemaConfig {
 export async function discoverBlocks(
 	blockPackages: string[],
 ): Promise<DiscoveredBlocks> {
-	// Scope discovery to what is ACTUALLY INSTALLED, never the authored
-	// `block_packages` list. That list was an authored hint that silently
-	// DRIFTED: a page-used package missing from it caused its blocks to be
-	// skipped and rendered BLANK with only a warning (scala-sign, 2026-06-04 —
-	// SignIn / SignatureField / ScrollProgress all blanked because sign-in-block
-	// had fallen out of the list). The filesystem is the source of truth: a page
+	// Scope discovery to what is ACTUALLY INSTALLED, never the authored `block_packages` list. That list was an authored hint that silently
+	// DRIFTED: a page-used package missing from it caused its blocks to be skipped and rendered BLANK with only a warning (scala-sign, 2026-06-04 —
+	// SignIn / SignatureField / ScrollProgress all blanked because sign-in-block had fallen out of the list). The filesystem is the source of truth: a page
 	// can only compose blocks from packages installed as the service's
 	// dependencies, so "installed @teamgbg package" is always a correct superset
 	// of "packages the pages need". A block_schema whose package is installed is
@@ -70,7 +68,7 @@ export async function discoverBlocks(
 	if (blockPackages.length > 0) {
 		const stale = blockPackages.filter((p) => !isInstalled(p));
 		if (stale.length > 0) {
-			console.warn(
+			getAppLogger().warn(
 				`[discover-blocks] block_packages lists ${stale.length} package(s) that are not installed (ignored): ${stale.join(", ")}`,
 			);
 		}

package/src/fn-routers/agreement-certificate.ts

@@ -161,7 +161,7 @@ export async function buildCertificateData(
 			signature_data: unknown;
 			signer_email: string | null;
 			signer_name: string | null;
-		}[]
+		}
 	>`
 		SELECT id, name, created_at, sent_at, viewed_at, signed_at,
 		       signature_data, signer_email, signer_name