@teamscala/service-boot 0.23.524 → 0.23.526

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

@@ -3,48 +3,6 @@
  * @status handwritten
  */
 
-			// 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).
-
-			// 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.
-
-	// 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`).
-
 import { mkdir, readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
@@ -79,16 +37,6 @@ export async function buildHydrateBundle(
 
 	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",
@@ -112,21 +60,6 @@ export async function buildHydrateBundle(
 			entrypoints: [entry],
 			target: "browser",
 			outdir: outDir,
-			// THE BUNDLER OWNS THE HASH, because it also writes the references.
-			// Under `splitting: true` + `publicPath`, Bun bakes the entry's
-			// build-time name into every chunk that imports it. Naming the entry
-			// `hydrate.js` here and RENAMING it to `hydrate-<hash>.js` afterwards
-			// moved the file but could not rewrite the specifiers already emitted
-			// into the chunks — so every chunk imported `/assets/hydrate.js`, which
-			// no longer existed. 404 on the module, the importing block dies, and
-			// the page still returns 200 with every guard green.
-			//
-			// MEASURED 2026-09-08 on quiz.scala.business: `AssessmentFlowBlock`
-			// failed with "Failed to fetch dynamically imported module"; crawling
-			// the served graph (142 level-1 + 76 level-2 assets) found exactly one
-			// broken URL — `/assets/hydrate.js` — imported by the entry itself and
-			// by most chunks. Hash applied OUTSIDE the generator is two artefacts
-			// that must agree with nothing making them (`one-generator-pattern`).
 			naming: {
 				entry: `${HYDRATE_BASE}-[hash].[ext]`,
 				chunk: "chunk-[hash].[ext]",
@@ -135,36 +68,13 @@ export async function buildHydrateBundle(
 			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)))
@@ -182,12 +92,6 @@ export async function buildHydrateBundle(
 	}
 
 	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,
@@ -240,11 +144,6 @@ export async function buildHydrateBundle(
 		);
 	}
 
-	// Bun emitted the hashed entry itself, so the name it wrote into every
-	// chunk IS the name on disk. Read it back from the build's own output
-	// list rather than reconstructing it — a reconstructed name is a second
-	// copy of a fact the bundler already owns, which is the defect this
-	// change removes (`a-mutating-verb-reads-back-what-it-claims`).
 	const entryOutput = result.outputs.find(
 		(o) => o.kind === "entry-point",
 	);
@@ -255,12 +154,6 @@ export async function buildHydrateBundle(
 	}
 	const hashedName = entryOutput.path.split("/").pop() as string;
 	const hashedPath = join(outDir, hashedName);
-	// The bundler OWNS this name (naming.entry above). Read the release hash
-	// out of it; a name that no longer matches the declared
-	// hydrate-<hash>.js shape means the naming contract changed underneath
-	// us — refuse rather than re-derive a second hash from file bytes
-	// (`one-generator-pattern`): a fallback here would produce a release id
-	// the URL does not carry.
 	const hashMatch = /^hydrate-([A-Za-z0-9]+)\.js$/.exec(hashedName);
 	if (!hashMatch) {
 		throw new Error(
@@ -270,9 +163,6 @@ export async function buildHydrateBundle(
 	const hash = hashMatch[1];
 	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")
@@ -280,10 +170,6 @@ export async function buildHydrateBundle(
 	);
 	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) {
@@ -298,19 +184,11 @@ export async function buildHydrateBundle(
 		{ 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) + RETAIN the .map files
-	// outside the served root so a failed upload retries next boot — source
-	// never ships publicly. The currentOutputs set names the build's own
-	// bundles (entry + chunks) so maps from an older build don't pollute
-	// this release's cache and re-upload as stale artifacts.
 	const currentOutputs = new Set(
 		result.outputs
 			.filter((o) => o.kind === "chunk")
@@ -320,10 +198,6 @@ export async function buildHydrateBundle(
 	return { hydratePath: `/assets/${hashedName}`, sourceMaps };
 }
 
-// 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>,

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

@@ -35,13 +35,6 @@ export interface AssetManifest {
 	sourceMaps?: SourceMapUploadResult;
 }
 
-/**
- * Read ONLY the tombstone state of the current manifest — the runtime
- * (read-html-template, ui-service) calls this to decide whether to surface a
- * build-failure signal. Returns null when the manifest is fresh (no
- * `buildFailed`). Decoupled from the full AssetManifest read so the runtime
- * never depends on the build internals.
- */
 export async function readClientBuildStatus(
 	cwd = process.cwd(),
 ): Promise<{ failed: true; reason?: string; at?: string } | { failed: false }> {
@@ -93,17 +86,6 @@ export async function writeManifest(
 	);
 }
 
-/**
- * Verify the CURRENT manifest against the files it names — the capability
- * probe the readiness flip gates on (`a-component-may-not-report-a-state-it-
- * has-not-verified`). A manifest is servable only when BOTH referenced assets
- * exist on disk. An absent or unreadable manifest, a first-boot tombstone
- * carrying no paths, and any manifest naming files that do not exist must all
- * read as NOT built, never as a legitimate bundle. Measured 2026-09-01:
- * proposals.scala.business served a client-facing proposal unstyled while
- * Railway reported the deploy SUCCESS, because "client build never ran" was
- * indistinguishable from "client build fine" at every layer that reports.
- */
 export async function verifyClientBuildAssets(
 	cwd = process.cwd(),
 ): Promise<{ ok: true } | { ok: false; reason: string }> {

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

@@ -7,9 +7,6 @@ import { resolve } from "node:path";
 import { stat } from "node:fs/promises";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 
-// Directory-capable existence probe. Bun.file().exists() answers false for
-// directories, so the @source roots (directories by construction) were all
-// "absent" and the candidate scan returned nothing.
 async function existsStat(path: string): Promise<boolean> {
 	try {
 		await stat(path);
@@ -19,16 +16,6 @@ async function existsStat(path: string): Promise<boolean> {
 	}
 }
 
-// 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
-// `css-build-scans-source-candidates`.
 const SCAN_EXTS = new Set([
 	".ts",
 	".tsx",
@@ -40,9 +27,6 @@ const SCAN_EXTS = new Set([
 	".md",
 	".mdx",
 ]);
-// Class-name candidate chars: identifiers, variant `:`, opacity `/`, arbitrary
-// values `[]()`, decimals `.`, important `!`, plus `#%,&-` seen in arbitrary
-// values and modifiers. Deliberately broad — invalid tokens are dropped by build().
 const CANDIDATE_RE = /[A-Za-z0-9_:/[\].%#!,&-]+/g;
 
 export async function scanSourceCandidates(
@@ -58,23 +42,7 @@ export async function scanSourceCandidates(
 		} catch {
 			continue;
 		}
-		// A resolved @source root absent on disk is benign: a published block
-		// package ships compiled output, not its src/ tree, so an `@source` into
-		// 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.
-		// The probe MUST be a stat, never Bun.file(root).exists(): root is a
-		// DIRECTORY and Bun.file() on a directory reports exists() === false
-		// (the same defect discover-blocks.ts measured 2026-09-01). That probe
-		// skipped EVERY source, collapsed the candidate set to zero, and
-		// `build([])` stripped every Tailwind utility from every kind:ui
-		// service's stylesheet at once — the operator's "the css is totally
-		// fucked" with a stylesheet that loads and 15k package rules intact.
 		if (!await existsStat(root)) 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
-		// but never descend into node_modules (the entire dependency graph).
 		const rootInNodeModules = root.includes("/node_modules/");
 		try {
 			const glob = new Bun.Glob("**/*");
@@ -97,8 +65,6 @@ export async function scanSourceCandidates(
 				if (matched) for (const t of matched) candidates.add(t);
 			}
 		} catch (err) {
-			// A bad source dir never aborts the whole CSS build (the other
-			// sources still contribute their utilities).
 			log.warn(
 				`[build-client-assets] candidate scan skipped ${root}: ${
 					err instanceof Error ? err.message : String(err)

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

@@ -3,33 +3,6 @@
  * @status handwritten
  */
 
-/**
- * Upload source maps to GlitchTip via the official `glitchtip-cli` debug-ID
- * flow (the documented first-class mechanism — `sourcemaps inject` then
- * `sourcemaps upload --release`; see telemetry.md `client-errors-report-to-glitchtip`
- * + https://glitchtip.com/documentation/cli). Debug IDs injected into the served
- * bundles + uploaded maps are the matching mechanism — robust vs URL-prefix
- * guessing.
- *
- * THE MAPS OUTLIVE THE UPLOAD ATTEMPT: `.map` files are MOVED out of the
- * served root (`dist/client/` — /assets/* would serve source publicly) into
- * the retained cache `dist/sourcemaps/<release>/` BEFORE anything else, and
- * the upload runs from the cache. A failed or skipped upload therefore
- * leaves the maps on disk for the next boot's retry (the fingerprint-skip
- * path in build-client-assets.ts re-runs the upload whenever the manifest
- * does not record `uploaded`) instead of destroying the only copy of a
- * release's maps on an unverified claim (`a-component-may-not-report-a-
- * state-it-has-not-verified`; measured: the pre-2026-09 flow deleted the
- * maps after an upload whose responses were never checked, so a missing
- * token or a 4xx permanently lost a release's maps while the boot log kept
- * saying "uploaded").
- *
- * Every upstream response is verified: the release-create call must return
- * 2xx/208 and each file upload must return 2xx, else the failure is named
- * (status + body head) in the result. Best-effort at the SERVICE level — a
- * failed upload never blocks boot — but never at the CLAIM level: the
- * result says what actually happened and the manifest records it.
- */
 
 import { mkdir, readdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
@@ -41,35 +14,22 @@ export type SourceMapUploadStatus = "uploaded" | "failed" | "skipped";
 
 export interface SourceMapUploadResult {
 	status: SourceMapUploadStatus;
-	/** Maps verified accepted by GlitchTip (2xx), never assumed. */
 	uploaded: number;
-	/** Maps present for this upload pass (moved to the retained cache). */
 	total: number;
-	/** One named failure per non-accepted upload (status + body head). */
 	failures: string[];
 	at: string;
 }
 
 const UPLOAD_TIMEOUT_MS = 30_000;
 
-/** The retained, never-served home of a release's source maps. */
 export function sourceMapsCacheDir(cwd: string, release: string): string {
 	return join(cwd, "dist", "sourcemaps", release);
 }
 
-/** The release (bare content hash) a manifest's hydratePath names. */
 export function releaseFromHydratePath(hydratePath: string): string | null {
 	return /hydrate-([a-z0-9]+)\.js/.exec(hydratePath)?.[1] ?? null;
 }
 
-/**
- * Move every `.map` in `outDir` whose base filename is in `currentOutputs`
- * into the retained cache for `release`, then DELETE every other `.map` left
- * in `outDir` (stale maps from an older build whose release cache should
- * already hold a copy — or, on Railway ephemeral disk, was lost; either
- * way the served root must never hold one). Returns the names that were
- * moved into THIS release's cache.
- */
 async function moveMapsToCache(
 	cwd: string,
 	outDir: string,
@@ -112,7 +72,6 @@ function authEnv(): { token: string; url: string } | null {
 	return { token, url };
 }
 
-/** Upload the maps ALREADY RETAINED in the cache for `release`. */
 export async function uploadCachedSourceMaps(
 	cwd: string,
 	release: string,
@@ -144,7 +103,6 @@ export async function uploadCachedSourceMaps(
 	return uploadMapsFromCache(cacheDir, names, release, auth, log, at);
 }
 
-/** Upload source maps for the bundle just built into `outDir`. */
 export async function uploadSourceMaps(
 	cwd: string,
 	outDir: string,

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

@@ -22,9 +22,6 @@ export async function bunResolveStylesheet(
 		return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 	}
 	if (id.startsWith(".")) {
-		// Relative import: resolve against the importing file's directory and
-		// REQUIRE existence — a missing leaf is a build-breaking error naming
-		// the specifier, never a silently-dropped subtree.
 		const p = resolve(base, id);
 		if (!(await Bun.file(p).exists())) {
 			throw new Error(
@@ -33,28 +30,11 @@ export async function bunResolveStylesheet(
 		}
 		return { path: p, base: dirname(p), content: await Bun.file(p).text() };
 	}
-	// A BARE SPECIFIER IS A PACKAGE NAME PLUS AN OPTIONAL SUBPATH, and the two
-	// must be separated before anything is looked up. `@teamscala/ui-foundation`
-	// is a package; `@teamscala/ui-foundation/theme/styles.css` is that same
-	// package plus an explicit file inside it. Treating the whole string as a
-	// package name looks for node_modules/@teamscala/ui-foundation/theme/
-	// styles.css/package.json, which cannot exist — so EVERY subpath import
-	// fails and the styles bundle dies, taking the theme layer with it.
-	//
-	// A scoped name is the FIRST TWO segments (@scope/name); an unscoped name
-	// is the first. Everything after that is a path inside the package and is
-	// resolved directly — it names a file, so there is nothing to negotiate and
-	// no style entry to consult.
 	const segments = id.split("/");
 	const nameLength = id.startsWith("@") ? 2 : 1;
 	const packageName = segments.slice(0, nameLength).join("/");
 	const subpath = segments.slice(nameLength).join("/");
 
-	// Find node_modules/<packageName>/package.json by walking upward from the
-	// importing file's dir then cwd. Bun.resolve is not used: it hands back
-	// whatever the package's main is — for a normal JS package a .js entry,
-	// not the declared stylesheet — and an `exports` allow-list blocks the
-	// package.json subpath on exactly the CSS-only packages this must serve.
 	const tried: string[] = [];
 	for (const root of [base, cwd]) {
 		let dir = root;
@@ -64,13 +44,6 @@ export async function bunResolveStylesheet(
 				const pkgDir = dirname(pkgPath);
 				const pkg = await Bun.file(pkgPath).json();
 				if (subpath) {
-					// THE EXPORTS MAP IS THE AUTHORITY ON WHERE A SUBPATH LIVES,
-					// and it commonly REMAPS. `@teamscala/ui-foundation` publishes
-					// "./theme/styles.css" -> "./src/theme/styles.css", so resolving
-					// the subpath literally against the package root looks for a
-					// file that has never existed there. Consult exports first and
-					// fall back to the literal path only for a package that
-					// declares none.
 					const exported = pkg.exports?.[`./${subpath}`];
 					const mapped: string | undefined =
 						typeof exported === "string"
@@ -87,7 +60,6 @@ export async function bunResolveStylesheet(
 					}
 					return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 				}
-				// No subpath: the package itself must declare its stylesheet.
 				const entry: string | undefined = pkg.exports?.["."]?.style ?? pkg.style;
 				if (!entry) {
 					throw new Error(
@@ -108,16 +80,6 @@ export async function bunResolveStylesheet(
 	);
 }
 
-// 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).
-// So every remote @import is STRIPPED from the compiled bundle: a package can
-// never inject a CDN font/stylesheet, and the only font source is the app-owned
-// index.html link. Fixed once at the single CSS chokepoint; guarded by
-// `css-build-strips-remote-imports`.
 const REMOTE_IMPORT_RE =
 	/^[ \t]*@import\s+(?:url\(\s*)?["']https?:\/\/[^"')]+["']\s*\)?[^;]*;[ \t]*\n?/gm;
 
@@ -144,16 +106,6 @@ export async function buildTailwindCss(
 	await mkdir(outDir, { recursive: true });
 
 	const cssSource = await Bun.file(entry).text();
-	// base MUST be the ENTRY FILE's directory (src/), never the service root.
-	// The generated app.css authors its @source dirs relative to itself
-	// ("../node_modules/@teamscala/<pkg>/src"); Tailwind 4.3 resolves @source
-	// against THIS base, so passing the service root aimed every scan one
-	// level too high (workspace/node_modules — empty) and the candidate set
-	// collapsed to zero: build([]) strips every Tailwind utility and every
-	// kind:ui service renders with naked buttons/controls while the
-	// stylesheet still loads with its full package-rule payload (measured
-	// 2026-09-05, operator-visible fleet-wide). Package-specifier @imports are
-	// unaffected — they resolve through loadStylesheet's Bun.resolve walk.
 	const compiler = await compile(cssSource, {
 		base: join(cwd, "src"),
 		async loadStylesheet(id, base) {
@@ -166,8 +118,6 @@ export async function buildTailwindCss(
 		},
 	});
 
-	// Scan every resolved @source for candidate class names — WITHOUT this the
-	// build emits no content-driven utilities (the unstyled-editor bug above).
 	const candidates = await scanSourceCandidates(compiler.sources, log);
 	const cssOutput = stripRemoteImports(compiler.build(candidates));
 	log.info(

package/src/capability-slug.ts

@@ -3,23 +3,13 @@
  * @status handwritten
  */
 
-/** Language segment of a deployable name. `bun` is the retired spelling. */
 const LANGUAGES = ["ts", "bun", "rust"] as const;
 
-/** Tier segment of a deployable name. */
 const TIERS = ["dev", "prod"] as const;
 
 type Language = (typeof LANGUAGES)[number];
 type Tier = (typeof TIERS)[number];
 
-/**
- * The capability half of a deployable slug.
- *
- * `scala-projects-ts-dev`   -> `scala-projects`
- * `scala-projects-ts-prod`  -> `scala-projects`
- * `scala-projects-bun-dev`  -> `scala-projects` (retired spelling)
- * `scala-projects`          -> `scala-projects` (already a capability name)
- */
 export function toCapabilitySlug(slug: string): string {
 	const parts = slug.split("-");
 	if (parts.length < 3) return slug;

package/src/compose-page-title.ts

@@ -4,20 +4,11 @@
  */
 
 export interface TitleContext {
-	/** Per-page override (builda_pages.meta_title). Wins outright when set. */
 	pageMetaTitle?: string | null;
-	/** Resolved resource-template string (forms/quiz/gpt). Curated per-surface shape. */
 	templateTitle?: string | null;
-	/** builda_websites.name — the surface, the legacy site context (orgPrefix off). */
 	websiteName?: string | null;
-	/** The OWNING ORG's display name (brand.companyName, resolved from the
-	 * org the page's brand_org_path names). The title prefix when orgPrefix is
-	 * on — operator ruling 2026-08-17: a client-facing document's tab carries
-	 * the org's name, never the internal website label ("Public Pages"). */
 	organisationName?: string | null;
-	/** builda_pages.name — the page (e.g. "Dashboard"). */
 	pageName?: string | null;
-	/** Resource entity title (proposal/form/quiz/agent name) — preferred subject. */
 	entityTitle?: string | null;
 }
 

package/src/content-gate/access.ts

@@ -30,36 +30,17 @@ export async function attachContentGateAccess(
 		let email = "";
 		let name = "";
 		let phone = "";
-		// Optional prospect segmentation a capture gate's composed form may post
-		// (the quiz identity screen: company, LinkedIn, website, team size). Every
-		// field is optional and every reader treats absence as "" — a gate that
-		// never collects them (the GPT) is unaffected, and a form that collects
-		// only some carries the rest as absent. Field names follow the response
-		// columns the segmentation lands in (linkedin_url / team_size, snake case)
-		// because the composed form posts exactly what its FormField rows name.
 		let company = "";
 		let linkedinUrl = "";
 		let website = "";
 		let teamSize = "";
 		let bodyFailed = false;
-		// The resource id may ride on the URL instead of the body. A gate whose
-		// form is COMPOSED FROM BLOCKS has no place to put a hidden field — the
-		// generic submit action collects the visible inputs and adds only the
-		// static fields its row declares, and a row is shared by every page so it
-		// cannot carry a per-page id. The gate therefore publishes its own access
-		// URL with the id already on it (see quiz-gate onUnauthorized), which
-		// keeps the id single-sourced from the resolved graph. A body field still
-		// wins where one is posted (proposals, agreements, the GPT).
 		const queryResourceId = String(c.req.query(config.recordIdField) ?? "").trim();
 		try {
 			const form = await c.req.parseBody();
 			resourceId = String(form[config.recordIdField] ?? "").trim() || queryResourceId;
 			email = String(form.email ?? "").trim().toLowerCase();
-			// Optional captured display name (open-capture gates carry it in the
-			// token; allow-list gates ignore it via signToken).
 			name = String(form.name ?? "").trim();
-			// Captured alongside the email by an open-capture gate's composed
-			// form. It rides in the signed token rather than any client store.
 			phone = String(form.phone ?? "").trim();
 			company = String(form.company ?? "").trim();
 			linkedinUrl = String(form.linkedin_url ?? "").trim();
@@ -74,9 +55,6 @@ export async function attachContentGateAccess(
 
 		let matched = false;
 		if (config.openCapture) {
-			// Open lead-capture gate (the public GPT): any non-empty email is a
-			// valid visitor — there is no allow-list to authorize against. We
-			// already required a non-empty email above, so this is a match.
 			matched = true;
 		} else {
 			try {
@@ -112,10 +90,6 @@ export async function attachContentGateAccess(
 				`${config.cookieName}=${encodeURIComponent(token)}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,
 			);
 			if (config.entryCookieName) {
-				// The ENTRY MARKER: it authorizes exactly the redirect this sets it
-				// on — the gate requires it and the render it consumed clears it.
-				// Max-Age matches the token only as a safety net; consumption is
-				// what ends its life, never the clock.
 				c.header(
 					"Set-Cookie",
 					`${config.entryCookieName}=1; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${maxAge}`,

package/src/content-gate/catalog.ts

@@ -3,33 +3,7 @@
  * @status handwritten
  */
 
-/**
- * Registered gates, in evaluation order.
- *
- * ORDER IS LOAD-BEARING AND SO IT IS DECLARED, NOT INCIDENTAL. Proposals run
- * before agreements: an authorized proposal viewer has their gate block removed
- * from the resolved graph, after which the agreement gate finds no resource and
- * no-ops. Reversing these two changes behaviour on a page carrying both.
- *
- * Each gate still self-selects — `getResourceId` returns "" when the page is not
- * its kind — so listing a gate here never makes it apply to a page it does not
- * govern.
- */
 
-/**
- * Does this gate WITHHOLD content, or only identify the visitor?
- *
- * DERIVED FROM THE ACCESS CONFIG, NEVER DECLARED TWICE. `openCapture` already
- * states that any email is a valid visitor, which is precisely the case where
- * nothing is being withheld — the GPT page body is public and only its identity
- * is gated (see gptGateConfig.onUnauthorized, a documented no-op). A separate
- * `withholdsContent` flag would be a second copy of that fact, free to drift
- * from the one the access endpoint actually enforces (`offered-is-derived`).
- *
- * The distinction matters to the assistant: a seed-only gate must not count as
- * "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.
- */
 
 import type { AccessConfig, ContentGateConfig } from "./config-types.ts";
 import { agreementAccessConfig, agreementGateConfig } from "../agreement-gate.ts";
@@ -37,9 +11,7 @@ import { gptAccessConfig, gptGateConfig } from "../gpt-gate.ts";
 import { proposalAccessConfig, proposalGateConfig } from "../proposal-gate.ts";
 import { quizAccessConfig, quizGateConfig } from "../quiz-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;
@@ -56,7 +28,6 @@ export function withholdsContent(entry: ContentGateEntry): boolean {
 	return entry.access.openCapture !== true;
 }
 
-/** The gates that can withhold content, in order — the assistant's authority. */
 export function contentWithholdingGates(): ContentGateEntry[] {
 	return CONTENT_GATES.filter(withholdsContent);
 }