@teamscala/service-boot 0.23.432 → 0.23.434

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.432",
+  "version": "0.23.434",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",

package/src/auth-gate.ts

@@ -44,9 +44,6 @@
  * registry refused a path exemption for it, correctly — `guard-exemptions-to-zero`.
  */
 
-// Why: Point the event-log primitive at the process's Prisma single…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// Eager-warm the local BetterAuth runtime at boot whenever a request path
 	// will build it: the session-READ path (getSession, better-auth-cookie mode)
 	// always uses the local instance — even when /api/auth/* forwards to
@@ -61,9 +58,6 @@
 	// (e.g. mid-install) the first successful request rebuilds and caches — the
 	// service is never left wedged, and never boot-loops on a transient.
 
-// Why: Eager-warm the local BetterAuth runtime at boot whenever a r…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 		// NO localhost bypass: a 127.0.0.1 page request is gated EXACTLY like a
 		// tunnel request (no session → redirect to /sign-in). The old
 		// `if (isLocalhost) return next()` let any tool — and the agent's own
@@ -76,9 +70,6 @@
 		// service-to-service auth still flows through the cookie/secret on the
 		// request, never the source IP.
 
-// Why: NO localhost bypass: a 127.0.0.1 page request is gated EXACT…
-// (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 { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
 import { getPrisma } from "@teamscala/db/prisma-registry";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";

package/src/bind-page-handler.ts

@@ -21,9 +21,6 @@
 		// 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.
 
-// Why: Per-page root.props.maxWidth (the canonical mechanism) cente…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Context } from "hono";
 import { readHtmlTemplate } from "./read-html-template.ts";

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

@@ -27,9 +27,6 @@
 			// 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).
 
-// Why: Externalize an unresolvable @teamscala/* block import (a dea…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 			// 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
@@ -42,9 +39,6 @@
 			// gate below fails the build LOUD if this or any future regression slips
 			// a fatal facade through on any UI service.
 
-// Why: minifyIdentifiers is DISABLED (whitespace + syntax/dead-code…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// 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
@@ -61,9 +55,6 @@
 	// be silently bypassed; a valid local-export chunk carries a
 	// class/function/const/var/let/import, a valid re-export carries `from`).
 
-// Why: dead-facade prevention gate (agents.scala.business 2026-07-2…
-// (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, readdir, rename, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";

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

@@ -31,9 +31,6 @@
 //    @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
@@ -46,9 +43,6 @@
 	// 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-
@@ -64,9 +58,6 @@
 	// 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,

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

@@ -23,9 +23,6 @@
  * 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";

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

@@ -35,7 +35,7 @@ async function resolveStylesheetRaw(
 		const r = await Bun.resolve(id, base);
 		return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 	} catch (error) {
-		log.warn("style import resolve failed — trying package fallback", error);
+		getAppLogger().warn("style import resolve failed — trying package fallback", error);
 	}
 	if (!id.startsWith(".")) {
 		try {
@@ -48,7 +48,10 @@ async function resolveStylesheetRaw(
 				return { path: r, base: dirname(r), content: await Bun.file(r).text() };
 			}
 		} catch (error) {
-			log.warn("package style entry resolve failed — falling back to bare resolve", error);
+			getAppLogger().warn(
+				"package style entry resolve failed — falling back to bare resolve",
+				error,
+			);
 		}
 	}
 	const r = resolve(base, id);

package/src/build-client-assets.ts

@@ -52,9 +52,6 @@
 	// 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";

package/src/content-gate/catalog.ts

@@ -39,9 +39,6 @@
  * govern.
  */
 
-// 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?
  *
@@ -57,9 +54,6 @@
  * 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";

package/src/content-gate/gate.ts

@@ -25,9 +25,6 @@
  * 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";
 

package/src/fn-routers/agreement-sign-side-effects.ts

@@ -32,9 +32,6 @@
  * payUrl) before this runs; only the stored record is reset.
  */
 
-// Why: Self-resetting demo harness. If the signed agreement's `prop…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { queryRows } from "@teamscala/db/query-rows";
 import type { PrismaClient } from "@teamscala/db/client";

package/src/fn-routers/index.ts

@@ -13,10 +13,24 @@
  * RegionPageSwap can fetch a region's Puck page on demand and render it into a
  * slot — the no-reload half of `region-views-are-pages` (every region is a Puck
  * page; switching a view loads a different page's content).
+ *
+ * `resolvePanelData` WAS RESTORED 2026-08-31. `72ac1a7` ("Retire unoffered page
+ * ORPC procedures") deleted it three weeks earlier as unoffered, but its
+ * consumer is live and in ANOTHER REPO: `use-region-page.ts` in
+ * @teamscala/ui-foundation calls `regions.resolvePanelData` on every panel
+ * open. Only the comment describing it was left behind — the shape
+ * `a-deleted-producer-leaves-its-consumers-executing` names, where deleting a
+ * producer leaves its consumers demanding something that can no longer exist.
+ *
+ * It failed SILENTLY for three weeks because the client treats a failure as
+ * best-effort and maps it to null, so the 404 rendered an empty panel with no
+ * error anywhere. Observed live as `POST /api/rpc/regions/resolvePanelData 404`
+ * on every panel open on projects-dev.
  */
 
 import { registerCustomRouter } from "@teamscala/orpc/app-router";
 import { puckPagesRouter } from "../page-server-orpc/puck-pages-router";
+import { resolvePanelDataHandler } from "./panel-data-router.ts";
 import { watchDataChange } from "@teamscala/realtime-utils/data-change-procedure";
 import { watchPresence } from "@teamscala/realtime-utils/presence-procedure";
 import { agreementSendRouter } from "./agreement-send-router.ts";
@@ -51,6 +65,8 @@ export function registerFnRouters(): void {
 		loadPage: puckPagesRouter.loadFromWebsite,
 		// Resolve a page-kind panel's OWN loaderData (panel_view.loader_slug) so a
 		// panel region renders against the panel page's data, not the host's.
+		//
+		resolvePanelData: resolvePanelDataHandler,
 	});
 	registerCustomRouter("realtime", {
 		watchDataChange,

package/src/fn-routers/panel-data-router.ts

@@ -0,0 +1,104 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * `regions.resolvePanelData` — resolves a page-kind panel's OWN loaderData so a
+ * panel region renders blocks against the panel page's data, not the host
+ * page's. RegionPageSwap calls this on panel-open + injects the result via
+ * LiveDataProvider("page-data"), making panel-embedded data blocks (e.g. the
+ * workload Chart) self-sufficient: each panel carries its own data, no host
+ * coupling + no preloading the host route.
+ *
+ * Flow (registry reads via the loadRegistryConfig helper — registry-via-helper):
+ * panel_view.content.loader_slug → resource_loader config → orgId derived from
+ * the serving website (builda_websites.organisation_id) → resolveFromLoaderConfig
+ * → the loader's resolved sources. Panels without a loader_slug (e.g. the AI
+ * panel, whose block self-loads) return null — no extra round-trip, no behavior
+ * change.
+ */
+import { os } from "@orpc/server";
+import * as v from "valibot";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import type { PanelViewKey } from "@teamscala/db/registry/generated/panel-view";
+import type { ResourceLoaderKey } from "@teamscala/db/registry/generated/resource-loader";
+import { resolveFromLoaderConfig } from "../resolve-from-loader-config.ts";
+
+interface Context {
+	prisma: {
+		builda_websites: {
+			findFirst: (args: unknown) => Promise<{
+				organisation_id?: string | null;
+			} | null>;
+		};
+	};
+}
+
+const panelViewSchema = v.looseObject({
+	content: v.looseObject({ loader_slug: v.optional(v.string()) }),
+});
+
+export const resolvePanelDataHandler = os
+	.$context<Context>()
+	.input(
+		v.object({
+			panelSlug: v.string(),
+			websiteSlug: v.string(),
+			/** Tenant orgId (preferred over the website's organisation_id, which is
+			 * the platform org on a multi-tenant portal — not the tenant). The
+			 * caller (RegionPageSwap) threads this from __PAGE_DATA__.orgId. */
+			orgId: v.optional(v.string()),
+		}),
+	)
+	.handler(async ({ input, context }) => {
+		// panel_view → loader_slug (null when missing or the panel has no loader).
+		let loaderSlug: string | undefined;
+		try {
+			// THE SLUG IS RUNTIME-SUPPLIED, so it cannot be statically a
+			// PanelViewKey: it arrives from the browser as the opened panel's
+			// name. The lookup itself is the validation — loadRegistryConfig
+			// throws when no such row exists, and the catch below turns that into
+			// the documented null. Narrowing here states that contract rather
+			// than asserting the value is known good.
+			const pv = await loadRegistryConfig(
+				"panel_view",
+				input.panelSlug as PanelViewKey,
+				panelViewSchema,
+			);
+			loaderSlug = pv.content?.loader_slug;
+		} catch {
+			return null;
+		}
+		if (!loaderSlug) return null;
+		// resource_loader → its config (loose schema; resolveFromLoaderConfig owns
+		// the typed LoaderConfig contract).
+		let loader: unknown;
+		try {
+			loader = await loadRegistryConfig(
+				"resource_loader",
+				// Same contract: loader_slug is read from the panel row's loose
+				// content schema as a plain string, and a missing row throws into
+				// the catch below.
+				loaderSlug as ResourceLoaderKey,
+				v.unknown(),
+			);
+		} catch {
+			return null;
+		}
+		// Tenant orgId: prefer the caller-provided value (the route's tenant org,
+		// threaded from __PAGE_DATA__.orgId); fall back to the website's
+		// organisation_id (the platform org — wrong for multi-tenant portals, but
+		// the only derivable value when the caller omits it).
+		let orgId = input.orgId;
+		if (!orgId) {
+			const site = await context.prisma.builda_websites.findFirst({
+				where: { OR: [{ slug: input.websiteSlug }, { id: input.websiteSlug }] },
+				select: { organisation_id: true },
+			});
+			orgId = site?.organisation_id ?? undefined;
+		}
+		return await resolveFromLoaderConfig(
+			loader as Parameters<typeof resolveFromLoaderConfig>[0],
+			{ orgId },
+		);
+	});

package/src/fn-routers/work-items-router.ts

@@ -33,9 +33,6 @@
 	 * dependent client-side round-trip chain).
 	 */
 
-// Why: Org-scoped member list for the task-comments panel — @mentio…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { createEmailClient } from "@teamscala/email-client/client";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { authed, type Context } from "./auth-router.ts";

package/src/handlers/platform-fault-escalation/orpc-client.ts

@@ -27,9 +27,6 @@
  * never Date instances (the generated valibot schemas require it).
  */
 
-// Why: The system-authed in-process ORPC client, built LAZILY on fi…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 import { createCache } from "@teamscala/cache/create-cache";

package/src/handlers/scala-tools-currency-watch.ts

@@ -45,9 +45,6 @@
 		// If a future package genuinely needs a restart to take effect, it does not belong here: add it to dep-sync's PM2_CACHED map, which already owns
 		// install-plus-restart and coalesces them.
 
-// Why: NO RESTART. The reinstall alone is sufficient, and restartin…
-// (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 { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";

package/src/handlers/singleton-tools-currency-watch.ts

@@ -40,9 +40,6 @@
  * tracking, never placement.
  */
 
-// Why: Where a tool's "latest" comes from.
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 		// A GitHub-released binary is NOT installed by a package manager, so there
 		// is no "reinstall" verb to call — it would have to be downloaded, verified,
 		// made executable and swapped atomically over a file that may be RUNNING.
@@ -55,9 +52,6 @@
 		// watcher cannot actually install is honest — silently claiming currency
 		// would not be.
 
-// Why: A GitHub-released binary is NOT installed by a package manag…
-// (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 { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { recordEvent } from "@teamscala/event-log/record-event";

package/src/mount-server-packages.ts

@@ -24,9 +24,6 @@
  * only warms the cache, never gates boot.
  */
 
-// Why: Speculatively import every server_package's mount module so …
-// (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 { ServiceInstallConfig } from "@teamscala/db/registry/loader/load-service-install-row";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";

package/src/register-page-server-client.ts

@@ -21,9 +21,6 @@
 		// rather than reporting a state it has not verified (`a-component-may-not-report-a-state-it-has-not-verified`). A service
 		// that declares no models (daemon/portal shells owning no DB schema) still passes through cleanly.
 
-// Why: REFUSE, DO NOT SKIP. `existsSync(routerPath)` being false us…
-// (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 { getAppLogger } from "@teamscala/logger/app-loggers";
 

package/src/register-registry-page-route/ai-chat-prefetch.ts

@@ -20,9 +20,6 @@
  * createOrRestore fallback, never an error page.
  */
 
-// Why: SSR-prefetch the signed-in user's AI-chat conversation so a …
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getServerClient } from "../page-server-orpc/server-client.ts";
 
 /**

package/src/register-registry-page-route/apply-page-branding.ts

@@ -28,9 +28,6 @@
  * Shared helper so this and bind-page-handler cannot drift on the answer.
  */
 
-// Why: /sign-in brand override: a shared org-scoped link 302→/sign-…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * brand-is-org-owned-full-scheme, reconciled with page-org-first
  * (portal-branding-resolves-page-org-first): the session override now
@@ -53,9 +50,6 @@
  * got the wrong page.
  */
 
-// Why: brand-is-org-owned-full-scheme, reconciled with page-org-fir…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's owner.
  * A public resource page (an assessment report, a shared document) is
@@ -77,9 +71,6 @@
  * more specific owner, never blank it.
  */
 
-// Why: BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { fetchOrganisationPageBranding } from "@teamscala/db/fetch-organisation-page-branding";
 import { getPlatformOrgId } from "@teamscala/db/registry/platform";
 import { getAppLogger } from "@teamscala/logger/app-loggers";

package/src/register-registry-page-route/graph-cache.ts

@@ -40,9 +40,6 @@
  * (an observable dead-link signal, not a hard error).
  */
 
-// Why: Stale-while-revalidate read of a cached loader graph.
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { createCache } from "@teamscala/cache/create-cache";
 
 // The structural surface readCachedGraph touches (getWithMeta + refreshInBackground).

package/src/register-registry-page-route/meta-title.ts

@@ -33,9 +33,6 @@
  * edit here rather than a fourth branch in three files.
  */
 
-// Why: THE ONE SUBJECT DERIVATION. What a page is ABOUT — the entit…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { interpolateMeta } from "../resolve-from-loader-config.ts";
 
 export function buildMetaFromContext(

package/src/register-registry-page-route/prefetch-org-id.ts

@@ -27,9 +27,6 @@
  * (found 2026-07-21).
  */
 
-// Why: Prefer segment 1; fall back to segment 0 only when segment 1…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 export function resolveAiOrgId(pathname: string): string | undefined {

package/src/register-registry-page-route/proposal-approval-email-token.ts

@@ -24,9 +24,6 @@
  * pages; other registry pages are untouched.
  */
 
-// Why: Resolve the `{{approvalEmail}}` placeholder in a proposal pa…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getServerClient } from "../page-server-orpc/server-client.ts";
 
 export async function applyApprovalEmailToken(

package/src/resolvers/portal-route-paths.ts

@@ -31,9 +31,6 @@
  * neither leading segment is a UUID.
  */
 
-// Why: Extract the organisation id from a portal-shaped callback/pa…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 export interface ResolverArgs {
 	input: Record<string, unknown>;
 	client: unknown;

package/src/resource-chat-inject.ts

@@ -36,9 +36,6 @@
  * column holds them yet.
  */
 
-// Why: THE ASSISTANT'S WORDS BELONG TO THE AGENT ROW, NOT TO THIS F…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * The rendered content tree to append the launcher to.
  *
@@ -67,9 +64,6 @@
  * caller. One shared convention, not a per-resource list.
  */
 
-// Why: The rendered content tree to append the launcher to.
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * Serialise EVERYTHING THIS VIEWER MAY SEE as text for the assistant.
  *
@@ -101,9 +95,6 @@
  * safe rather than reckless.
  */
 
-// Why: Serialise EVERYTHING THIS VIEWER MAY SEE as text for the ass…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { getServerClient } from "./page-server-orpc/server-client.ts";

package/src/resource-not-found.ts

@@ -47,9 +47,6 @@
  * HTML; the page renders logo-less, never broken.
  */
 
-// Why: The host org's LOGO (wordmark) for the dark error page — the…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getClient } from "@teamscala/object-storage/create/client/get-client";
 import { createCache } from "@teamscala/cache/create-cache";
 import { registerCacheInvalidation } from "@teamscala/db/notify-listener/index";

package/src/two-phase-full-app.ts

@@ -22,9 +22,6 @@
  * so we don't need to modify the app here. The app reference stays the same.
  */
 
-// Why: Build the full app with hydration. This adds the expensive o…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// Client asset building (expensive: Vite build).
 	//
 	// ISOLATED, because a PRESENTATION failure must not take out BACKGROUND WORK.
@@ -45,9 +42,6 @@
 	// registry and the DB, not a bundle. Ordering it behind a Vite build was
 	// incidental, so the coupling was never intended.
 
-// Why: Client asset building (expensive: Vite build).
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// pg-boss (mount for UI services - wasn't mounted in minimal app)
 	//
 	// Wrapped for the SAME reason buildClientAssets above is, in the other
@@ -62,9 +56,6 @@
 	// migration threw, and an outage of every page followed from a scheduled-job
 	// dependency. Jobs are the degradable half; pages are not.
 
-// Why: pg-boss (mount for UI services - wasn't mounted in minimal a…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import type { Hono } from "hono";
 import { buildClientAssets } from "./build-client-assets.ts";

package/src/two-phase-minimal-app.ts

@@ -29,9 +29,6 @@
  * - ORPC router, API routes, WS routes, data routes, page routes
  */
 
-// Why: Build the minimal tool-only app. This excludes the expensive…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// Fire independent I/O + compilation NOW, overlapping with the gate chain
 	// below. These three touch NO app route and have no ordering dependency on
 	// the gate/mount sequence, so they run concurrently with it:
@@ -45,9 +42,6 @@
 	// - discoverBlocks: loads the page-manifest (no app mutation, no gate
 	//   dependency). Its result is consumed by registerPageRoutes much later.
 
-// Why: Fire independent I/O + compilation NOW, overlapping with the…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";
 import { createTimer } from "@teamscala/timing/create-timer";

package/src/two-phase-readiness.ts

@@ -30,9 +30,6 @@
  * still reported starting — while three untouched UI services reported ok.
  */
 
-// Why: Flip readiness once phase 2 has built the full app.
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * Reset both phase-2 flags. TEST-ONLY.
  *
@@ -48,9 +45,6 @@
  * the only writers on the boot path.
  */
 
-// Why: Reset both phase-2 flags. TEST-ONLY.
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 /**
  * `/health` for a UI service — 200 ONLY once the full app can actually render
  * a page, 503 before that.
@@ -94,9 +88,6 @@
  * one consumer contract is "can you serve me a page", is moved to phase 2.
  */
 
-// Why: `/health` for a UI service — 200 ONLY once the full app can …
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { buildWakingPageHtml } from "@teamscala/os/brand/waking-page-html";
 import { WAKING_RETRY_SECONDS } from "@teamscala/os/brand/waking-page-budget.generated";
 import type { Context } from "hono";

package/src/ui-service.ts

@@ -22,9 +22,6 @@
  * place and is NOT undone.
  */
 
-// Why: Boots a UI service using two-phase boot for fast availabilit…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 	// Resolve the listen port through the SHARED resolver (`resolveServicePort`),
 	// the same one the backend branch uses. The registry wins wherever it has an
 	// opinion and a contradicting PORT env is reported, never silently obeyed —
@@ -39,9 +36,6 @@
 	// makes the healthcheck probe a dead port and the deploy fails (`isRailway`
 	// path in the resolver).
 
-// Why: Resolve the listen port through the SHARED resolver (`resolv…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 			// NO-SILENT-REVERTS — surface the failed client build to OBSERVABILITY
 			// (event-log → GlitchTip, per event-log-is-the-only-durable-event-log).
 			// The minimal-app fallback keeps serving SSR from the LAST-successful
@@ -55,9 +49,6 @@
 			// event-log's 7-day retention → surfaces in GlitchTip as an incident
 			// trail the operator actually watches.
 
-// Why: NO-SILENT-REVERTS — surface the failed client build to OBSER…
-// (full note hoisted to this file's leading header — kept out of the body per
-// no-inline-prose-blocks / prose-stays-in-docs)
 import { recordEvent } from "@teamscala/event-log/record-event";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { BootFatalError } from "@teamscala/os/errors/boot-error";