@teamscala/service-boot 0.23.523 → 0.23.525

package/src/auth-gate/public-paths.ts

@@ -1,15 +1,6 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The auth gate's public-path surface: sign-in paths, the static-asset
- * extension predicate, and the public infra prefixes/paths (self-authenticating
- * service-to-service surfaces, dev-host infra reads, and the access-gate
- * rejection target).
- *
- * Split out of auth-gate.ts (436 lines) — byte-for-byte move; import paths
- * adjusted only.
  */
 
 export const SIGN_IN_PATHS = new Set([
@@ -22,16 +13,6 @@ export const SIGN_IN_PATHS = new Set([
 	"/magic-link",
 ]);
 
-/// A STATIC ASSET IS NEVER A PROTECTED RESOURCE, so it is decided by EXTENSION / rather than by remembering to list it.
-/// / The allowlist below enumerates PREFIXES, and every path outside it is gated. / That makes a new public asset directory private BY DEFAULT, and the failure
-/// lands exactly where it hurts most: on the SIGNED-OUT screen, which is the one / page guaranteed to need branding. `/assets/` was listed; `/logos/` never was,
-/// so `/logos/cropped.png` answered 302 → /sign-in and the browser rendered a / blank logo under a "starting up" splash. Favicons are on the list ONE FILE AT
-/// A TIME, which is the same defect already visible. / / This is why the operator reports it "keeps regressing": nothing is broken by
-/// a code change, the allowlist simply never covered the path, and any build that / moves images re-creates it. Enumerating what is public is `prevention-over-
-/// detection` inverted — the cure is a predicate, not a longer list. /
-/// Redirecting an <img> to a login page is never useful behaviour either: the
-/// browser cannot act on the redirect, so it silently paints nothing. Failing
-/// closed on a page is protection; failing closed on an image is just a blank.
 const STATIC_ASSET_EXTENSIONS = [
 	".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".bmp",
 	".woff", ".woff2", ".ttf", ".otf", ".eot",
@@ -47,17 +28,7 @@ export const PUBLIC_INFRA_PREFIXES = [
 	"/assets/",
 	"/api/assets/",
 	"/api/auth/",
-	// fn.signInFlow procedures serve the unauthenticated sign-in flow (config
-	// load, session check, portal list) — anonymous-allowed by design (return {}
-	// for no session). They replaced the former /api/data/sign-in-flow-config,
-	// /check-session, /portals HANDLER_MAP entries (handler-map-retirement).
 	"/api/rpc/fn/signInFlow/",
-	// scala-enroll device-onboarding: the machine-facing installer + register
-	// routes are TOKEN-authenticated (a single-use enrollment token issued by a
-	// logged-in, dev_access-approved operator), fetched by the onboardee via
-	// `irm`/`curl` with NO session cookie — so they must skip the page login
-	// gate, exactly like /mcp (Bearer) and /api/rpc/ws self-authenticate. The
-	// TOKEN is the delegated capability; issuance (/issue) stays login-gated.
 	"/provision/",
 ];
 
@@ -67,81 +38,15 @@ export const PUBLIC_INFRA_PATHS = new Set([
 	"/favicon.svg",
 	"/api/session",
 	"/api/rpc/ws",
-	// The MCP endpoint is a service-to-service surface with its OWN Bearer auth
-	// (the gateway sends `Authorization: Bearer SCALA_DEV_KEY`, validated by the
-	// MCP route handler). It must never be session-page-gated: on a kind:ui
-	// service that also mounts an MCP server (scala-agents — the fleet
-	// orchestration + cross-pane channel), the auth-gate would 302 /mcp to
-	// /sign-in, so the gateway sees toolCount=0 and the whole channel goes
-	// degraded. Backend-only MCP hosts have no auth-gate, so this only bit the
-	// one UI MCP host once the localhost super-admin bypass was removed
-	// (the bypass had been masking it). Exempt alongside /api/rpc/ws and
-	// /api/auth/, which self-authenticate the same way.
 	"/mcp",
-	// build-id is polled by the client self-heal; it must always return JSON
-	// (a tiny bundle hash) regardless of session, never a /sign-in redirect —
-	// otherwise an expired-session tab would compare a redirect body to its
-	// booted build and never heal.
 	"/api/build-id",
-	// /_heap is the localhost-gated heap-attribution probe (register-static-assets);
-	// like /health it is infra, not a page, so it must never 302 to /sign-in on an
-	// auth-gated service. The probe's own localhost Host check is the real gate.
 	"/_heap",
-	// /api/fleet/events is the SSE fleet event stream consumed self-contained by
-	// the generated opencode scala-hooks plugin (and any future client without
-	// an @orpc/client dep) for native cross-pane channel delivery. The plugin
-	// runs in the opencode process with no scala-agents session cookie, so the
-	// route must be public; the stream is keyed by the orchestratorSessionId
-	// query param (the subscriber's own tmux pane id) and carries no sensitive
-	// data, and dispatch only emits events targeted at that identity.
 	"/api/fleet/events",
-	// /api/fleet/claude-sessions is a non-sensitive lane-identity read (active
-	// Claude lane sessionIDs + cwds) consumed by the session-picker daemon to
-	// RESTORE transcript tails after its own restart. The picker runs with no
-	// scala-agents session cookie; the data is less sensitive than the
-	// /api/fleet/events stream above (no message content), so it is public like
-	// the other dev-host infra reads.
 	"/api/fleet/claude-sessions",
-	// /api/fleet/ingest-event receives parsed lane-action events
-	// (message.part.updated etc.) from the cli-session transcript-tail — a
-	// dev-host INTERNAL machine caller that POSTs with no session cookie, exactly
-	// like the lane-event hook. Without this exemption the page auth-gate 302s
-	// every POST and the lane's tool/text action stream never reaches the
-	// ingestEvent pipeline. A first-class
-	// api_route (sibling to lane-event); security is the handler's loopback gate
-	// on the platform's x-caller-remote-address (set by register-api-routes).
 	"/api/fleet/ingest-event",
-	// /api/fleet/lane-event receives Claude Code http lifecycle hooks
-	// (Stop/UserPromptSubmit/Pre*ToolUse) for live-lane visibility. Like /mcp it
-	// is a service-to-service surface with its OWN Bearer auth (the hook sends
-	// `Authorization: Bearer SCALA_DEV_KEY`, validated by the handler); the hook
-	// runs in the Claude process with no scala-agents session cookie, so it must
-	// not be session-page-gated. The handler filters to fleet lanes by workspace
-	// cwd + resolves the lane via the session-picker, so an unauth'd caller
-	// writes no lane state.
 	"/api/fleet/lane-event",
-	// /api/fleet/sweep-executor receives the loga monitor engine's sweep dispatch
-	// (POST {slug}) -- a service-to-service surface like /api/fleet/lane-event /
-	// /api/fleet/ingest-event (loga -> scala-agents, localhost). Security is the
-	// handler's loopback gate (x-caller-remote-address), identical to its siblings.
 	"/api/fleet/sweep-executor",
-	// /api/terminal-ws is the in-browser terminal WebSocket bridge (a real PTY
-	// login shell). It is a dev-tool surface analogous to /api/fleet/events:
-	// the operator's own shell, no sensitive data beyond what the operator
-	// already has in their terminal. Must not be session-gated — the test
-	// harness and the terminal block both connect without a session cookie.
 	"/api/terminal-ws",
-	// /unauthorised is the access-gate's rejection target (the PageGuard access
-	// page). It MUST be exempt: an authed-but-not-allowed viewer is redirected
-	// here, so gating it would re-reject and loop. It renders no sensitive data.
 	"/unauthorised",
-	// The OpenAPI contract for the ORPC router — a service-to-service surface
-	// with its OWN Bearer auth (`Authorization: Bearer SCALA_DEV_KEY`,
-	// validated by the mount-orpc-router handler, fail-closed), exactly like
-	// /mcp and /api/fleet/lane-event above. The MCP gateway fetches it at boot
-	// (SCALA_OPENAPI_SPEC_URL) with no session cookie; without this exemption
-	// the page auth-gate 302s the fetch to /sign-in and the gateway reads an
-	// HTML sign-in page where the JSON document belongs (observed probing
-	// scala-portal.internal:5200/api/rpc/openapi.json on 2026-09-30).
 	"/api/rpc/openapi.json",
 ]);

package/src/auth-gate.ts

@@ -1,48 +1,8 @@
 /**
- * @system server-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Auth middleware factory. Three modes, same BetterAuth email-OTP mechanism:
- *
- *   service_install.auth values:
- *   - omitted | "none"            → no gate, no handler (scala-public, scala-sign)
- *   - "better-auth-cookie"        → full session auth: mount handler + session gate
- *   - "email-otp-only"            → mount handler (OTP send/verify), no session gate
- *
- *   The sign-in block determines the UX per mode:
- *   - "full"         → email → OTP → session → portal selection (portal, agents, docs, gpt)
- *   - "email-gate"   → email → OTP → verify-only, no session (forms, proposals, quiz)
- *   - "capture-only" → email field only, no OTP (sign)
- *
- *   There is NO localhost bypass: 127.0.0.1 is gated identically to the tunnel
- *   (no session → /sign-in). Tools needing an authed view sign in
- *   (getSuperAdminSessionCookie); the dev OTP is DB-readable.
- *
- *   When SCALA_OTP_URL is set, /api/auth/* forwards to the centralised
- *   scala-otp service (per otp-centralised-via-otp-service). Otherwise
- *   the local better-auth handler is used (dev-host fallback).
  */
 
-/**
- * Point the event-log primitive at the process's Prisma singleton.
- *
- * Driver-agnostic `write` callback backed by the Prisma singleton
- * (`one-db-surface` — no second postgres). Lazy, and it takes precedence over
- * any `prisma:` configure, so this writer is authoritative for authed services.
- * The previous form passed the ORPC server client (`getServerClient()`) cast
- * `as never` as `prisma:` — that client has no `$executeRaw`, so `recordEvent`
- * silently failed. Routing it through ORPC would reintroduce exactly that.
- * Retention is owned by the event-log-sweep pg-boss job.
- *
- * EXTRACTED so its name states what it is. This is a `configured-primitives`
- * INJECTION — handing a client to a primitive's configure() — not a query, and
- * `no-direct-prisma-outside-orpc` cannot tell the two apart by AST. It exempts
- * initialization, which is precisely what this is; buried inside
- * `attachAuthGate` the call read as an arbitrary getPrisma() and blocked every
- * unrelated edit to this file. Naming the boot step honestly is the fix. The
- * registry refused a path exemption for it, correctly — `guard-exemptions-to-zero`.
- */
 
 	// Eager-warm the local BetterAuth runtime at boot whenever a request path
 	// will build it: the session-READ path (getSession, better-auth-cookie mode)

package/src/bind-page-handler.ts

@@ -1,25 +1,8 @@
 /**
- * @system ui-service-boot
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * Calls a createPageHandler() handler with the per-request extras the
- * SSR pipeline needs: the resolved userId/orgId (from localhost-bypass
- * or better-auth-cookie), and the htmlTemplate. Shared by the regions
- * and page_slug shell variants.
  */
 
-		// Per-page root.props.maxWidth (the canonical mechanism) centers any page at the chosen width via inline styles — already hydration-safe
-		// and page-scoped. Bind-page-handler MUST NOT inject unscoped CSS selectors: a global `.puck-root-slot { max-width }` rule shrinks
-		// every portal pane that hosts a Puck root (the 2026-06-17 dashboard sliver bug — `.puck-root-slot` matches every Puck page in every
-		// region, including the dashboard center pane). The `no-bind-page-handler-css-injection` guard enforces this; this comment is the load-bearing rationale.
-		// Live dashboards must never be served from a stale cache (intermediary, browser back-forward, mobile Safari aggressive caching). Force every
-		// SSR HTML response to be revalidated. Static assets (CSS/JS bundles) keep their hash-busted caching — those are content-addressed.
-		// no-transform: intermediaries must not mutate SSR HTML — Cloudflare's Email Address Obfuscation rewrites mailto: hrefs at the edge, which
-		// breaks the server-serializes-client-reads-verbatim hydration contract (React recoverable-error on every page with a mailto link). Per CF
-		// docs, Email Obfuscation does not apply when no-transform is present. NOTE: a shared-edge-caching (CDN max-age) variant shipped briefly on 2026-06-10
-		// and was REMOVED by operator ruling the same day ("the origin should be so fast we don't care") — the origin-speed work (SWR caches,
-		// wave-parallel loader, brotli) is the sanctioned path; re-adding shared-cache headers needs a fresh operator ruling.
 
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { withGateEntryClears } from "./content-gate/gate-entry-clears.ts";
@@ -48,34 +31,12 @@ export async function bindPageHandler(
 		let orgId: string | undefined;
 		let visitor: { id: string; name: string; email: string } | null = null;
 
-		// NO localhost super-admin bypass: identity comes ONLY from the session
-		// (the auth-gate already forces sign-in for authed services on every
-		// host, 127.0.0.1 included). The old `if (isLocalhost) userId="super-admin"`
-		// rendered authed pages as a privileged user on localhost regardless of
-		// who (if anyone) was signed in — so agent/tool verification on 127.0.0.1
-		// saw a view that diverged from the real signed-in user's. Tools that need
-		// an authed render sign in and carry the cookie (getSuperAdminSessionCookie).
 
-		// The .scala.business session cookie reaches EVERY app on the domain,
-		// so a signed-in platform user is identifiable at SSR regardless of
-		// this service's own auth mode. Resolving it per-request (never via
-		// the cross-request loader graph) lets identity-gated blocks
-		// (PublicGptBlock's SignInBlock gate) first-paint the real experience
-		// instead of a client-side "checking who you are" loading pass
-		// (ssr-then-live-handoff). authMode still governs AUTHORIZATION;
-		// this is read-only identity convenience.
 		const hasSessionCookie = /better-auth\.session_token=/.test(
 			c.req.header("cookie") ?? "",
 		);
 
 		if (authMode === "better-auth-cookie" || hasSessionCookie) {
-			// Visitor identity is an ENHANCEMENT: on auth:none services
-			// (scala-public et al.) no auth factory is registered, and a
-			// signed-in operator's domain-wide cookie reaches every
-			// *.scala.business site — getSession throwing "Auth factory not
-			// registered" 500'd every page for signed-in visitors
-			// (public-dev outage, 2026-06-11). Degrade to anonymous, never
-			// fail the render (block-and-provider-error-isolation).
 			try {
 				const { getSession } = await import("@teamscala/auth/get-session.ts");
 				const session = await getSession(c.req.raw.headers);
@@ -92,27 +53,11 @@ export async function bindPageHandler(
 				}
 			} catch (err) {
 				if (authMode === "better-auth-cookie") throw err;
-				// cookie-only enhancement path: anonymous render proceeds
 			}
 		}
 
-		// Anonymous dynamic routes (proposal/form/quiz/agent) resolve a
-		// resource whose owning org is known from the loader. That org owns
-		// the brand the block-level serverLoaders read — override the
-		// viewer's org (if any) so the SSR injects the resource owner's
-		// logo/colours, not the viewer's.
 		if (resourceOrgId) orgId = resourceOrgId;
 
-		// Unauthed /sign-in (no session, no resource) would otherwise resolve no org, and the brand resolver falls back to the super-admin org (GBG Indo)
-		// — so a link shared to org A (e.g. GMG APAC) previews as org B's brand on WhatsApp/crawlers, because the link 302→/sign-in for the unauthed crawler.
-		// The callbackURL carries the org the visitor is signing in to; derive orgId from it so the sign-in page's brand/title/og reflect the destination org.
-		// The canonical portal shape is /<websiteId>/<orgId>/<path> — the org is segment 1, NOT segment 0. Reading segment 0 (the website id) fed a website
-		// id into brand resolution, which resolved no org and fell back to the super-admin org — the exact cross-tenant mis-branding this block exists to
-		// fix, still live until 2026-07-21; violates portal-branding-resolves-page-org-first.
-		// scala-projects routes /<orgId>/… (single UUID) and proposal/form/quiz hosts
-		// route /<resourceId>/… (a non-org first segment) — both keep segment 0 via
-		// the helper's single-UUID fallback (resolves to no brand, falls back as
-		// before). The helper is the single authority shared with the route resolver.
 		if (!orgId) {
 			const cb = c.req.query("callbackURL") ?? "";
 			const resolved = extractOrgIdFromCallbackPath(cb);
@@ -132,10 +77,6 @@ export async function bindPageHandler(
 			}),
 		);
 		const headers = new Headers(resp.headers as HeadersInit);
-		// Gate-entry markers are ONE-VIEW state: the render that consumed one
-		// clears it here, so the next load (a refresh) is unauthorized and shows
-		// the gate again. Without this the marker would outlive the view that
-		// used it and every load would skip the gate.
 		for (const name of gateEntryClears) {
 			headers.append(
 				"Set-Cookie",
@@ -148,26 +89,9 @@ export async function bindPageHandler(
 		);
 		headers.set("Pragma", "no-cache");
 		headers.set("Expires", "0");
-		// Viewport-aware slot loading varies the response by these headers.
-		// Even with Cache-Control: no-store, browsers and intermediaries
-		// honour Vary on back/forward navigation and BFCache; Accept-CH
-		// asks the browser to send Sec-CH-UA-Mobile on subsequent
-		// navigations (Chromium-family auto-sends, others opt in).
 		headers.set("Vary", "Sec-CH-UA-Mobile, User-Agent");
 		headers.set("Accept-CH", "Sec-CH-UA-Mobile");
-		// Origin-side gzip. Cache-Control: no-transform (load-bearing above —
-		// it disables Cloudflare HTML rewrites that corrupt hydration) ALSO
-		// makes hono's compress() middleware skip this response, which shipped
-		// 1.2MB of raw SSR HTML per page load through the dev tunnel (~3s of
-		// pure transfer; the operator's tablet timed out — 2026-06-06).
-		// no-transform forbids INTERMEDIARY transforms; origin-applied
-		// content-coding is part of the representation (RFC 9110 §8.4.1), so
-		// compressing here honors both. Bun.gzipSync on ~1.2MB costs ~10ms.
 		const acceptEnc = c.req.header("Accept-Encoding") ?? "";
-		// Brotli preferred when offered (every modern browser): ~15-20%
-		// smaller than gzip on SSR HTML. Quality 4, NOT the library default
-		// 11 — q11 costs hundreds of ms on a ~1MB page (defeats the point);
-		// q4 compresses in single-digit ms and still beats gzip.
 		if (/\bbr\b/.test(acceptEnc) && resp.body) {
 			const { brotliCompressSync, constants } = await import("node:zlib");
 			const raw = new Uint8Array(await new Response(resp.body as never).arrayBuffer());
@@ -187,8 +111,6 @@ export async function bindPageHandler(
 		}
 		return new Response(resp.body as never, { status: resp.status, headers });
 	} catch (err) {
-		// Dead entity link (wrong id, deleted row) → the branded not-found
-		// page with a real 404 — never a 500, never default-content leakage.
 		if (err instanceof PrimaryResourceMissingError) {
 			log.warn(
 				`[scala-install:${serviceSlug}] 404 ${err.resourceType} not found (${label}) for ${new URL(c.req.url).pathname}`,
@@ -197,10 +119,6 @@ export async function bindPageHandler(
 				err.resourceType,
 				await resolveErrorPageLogo(serviceSlug),
 				err.httpStatus,
-				// "Take me home" → the host root (relative "/" resolves to the
-				// current site's home; the portal redirects / to its dashboard).
-				// empty → the page-row-exists-but-zero-blocks "This page is empty"
-				// surface, distinct from a dead link (operator ruling 2026-07-21).
 				{ homeUrl: "/", empty: err.empty },
 			);
 		}

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

@@ -1,16 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @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";

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

@@ -1,16 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @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";

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

@@ -1,60 +1,8 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @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.
  */
 
-			// 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";
@@ -89,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",
@@ -122,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]",
@@ -145,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)))
@@ -192,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,
@@ -250,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",
 	);
@@ -265,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(
@@ -280,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")
@@ -290,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) {
@@ -308,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")
@@ -330,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

@@ -1,17 +1,6 @@
 /**
- * @system server-handlers
+ * @system service-boot
  * @status handwritten
- * @edit edit directly
- *
- * The asset-manifest unit of the client-asset build: the AssetManifest shape,
- * its read/write, the last-failure tombstone status read the runtime surfaces,
- * and the first-boot fallback paths.
- *
- * Split out of build-client-assets.ts (962 lines) alongside its build
- * siblings — the file held six concerns (manifest, hashed output, hydrate
- * bundle, source-map upload, stylesheet build, fingerprint, lock, orchestration).
- *
- * Byte-for-byte move from the parent — imports adjusted, nothing else.
  */
 
 import { join } from "node:path";
@@ -46,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 }> {
@@ -104,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 }> {