@teamscala/service-boot 0.23.524 → 0.23.525

package/src/pg-boss-mount.ts

@@ -14,25 +14,8 @@ import type { ScheduleOptions } from "pg-boss";
 import { PgBoss } from "pg-boss";
 import { pgBossHandlerRegistry } from "./pg-boss-handler-registry.ts";
 
-// Handlers register via their package's own boot hook / subscriber import
-// (package-subscriber shape) — no bundled copies. The mount resolves each
-// row's handler_slug against this registry at dispatch time.
 
 
-/**
- * Module-level reference to the mounted PgBoss instance — set by mountPgBoss on
- * successful start. Exposed via getPgBoss() so ORPC procedures (and other
- * in-process callers) can submit one-shot jobs via boss.send() without a second
- * PgBoss connection. Null before mount or when mountPgBoss found no scheduled
- * jobs for this service (boss never created).
- */
-let pgBossInstance: PgBoss | null = null;
-
-/** Returns the mounted PgBoss instance, or null if pg-boss is not running on this service. */
-export function getPgBoss(): PgBoss | null {
-	return pgBossInstance;
-}
-
 export interface PgBossMountContext {
 	databaseUrl: string;
 	serviceSlug: string;
@@ -59,9 +42,6 @@ function belongsToService(
 	const config = entry.config as Record<string, unknown>;
 	const handlerSlug = config.handler_slug as string | undefined;
 	if (!handlerSlug) return false;
-	// Explicit row-driven targeting takes precedence — a universal boot-package
-	// handler (e.g. one in @teamscala/service-boot, which no service declares in
-	// server_packages) cannot be scoped by the server_package prefix match.
 	const targetService = config.service_slug as string | undefined;
 	if (targetService) return targetService === serviceSlug;
 	return packages.some(
@@ -113,50 +93,13 @@ export async function mountPgBoss(
 	const log = getAppLogger();
 	const jobs: MountedJob[] = [];
 
-	// pg-boss connects through pg, whose sslmode dialect differs from the
-	// shared URL's libpq spelling — route through the canonical rewrite.
-	// Config object (not a bare connectionString) so the internal pool is
-	// bounded + tagged for the ~220ms cross-internet dev→Railway RTT.
-	// POLL-ONLY, EXPLICITLY. pg-boss v12 dispatches by polling (SELECT .. FOR
-	// UPDATE SKIP LOCKED inside a transaction; its locks are
-	// pg_advisory_xact_lock — transaction-scoped, so a transaction pooler
-	// cannot leak them); LISTEN/NOTIFY is a supplier-documented latency hint
-	// whose registration dies on a transaction-pooler backend reassignment
-	// (measured 2026-09-14: the opted-in sync worker boss logged
-	// `LISTEN/NOTIFY channel registration was lost` every log window).
-	// attorney.js defaults useListenNotify to false in 12.29.0 (pinned),
-	// 12.30.0 (deployed) and 12.31.1 (latest) — all three read directly —
-	// and spelling it here keeps that contract explicit so a pg-boss bump
-	// cannot silently re-introduce a LISTEN dependency
-	// (close-the-session-mode-door, 2026-09-14). The connection dials the
-	// injected DATABASE_URL — the transaction pooler — reconciling the pg
-	// sslmode dialect; the mount adds no endpoint derivation of its own.
 	const boss = new PgBoss({
 		useListenNotify: false,
 		connectionString: pgSslCompatUrl(ctx.databaseUrl),
 		application_name: `pgboss:${ctx.serviceSlug}`,
-		// ONE connection, not three: pg-boss is a sibling pool that sits OUTSIDE
-		// the Prisma budget, and with ~46 declared holders the fleet saturated
-		// at 304/300 (2026-08-27) partly on 3-connection pg-boss pools that had
-		// no idle timeout. At max:1 jobs serialize into a queue — the sanctioned
-		// background degradation (`a-per-consumer-pool-max-is-not-a-bound-on-the-server`:
-		// background work degrades to a queue, interactive work degrades to an
-		// outage). The sibling total is declared in
-		// config/db-pool-sizing.perServiceOverhead (pg-boss 1; the LISTEN allowance is gone with poll-only).
 		max: 1,
-		// Generous connection-acquisition budget for the cross-internet link so
-		// a slow TLS handshake under sustained load doesn't terminate the conn.
 		connectionTimeoutMillis: 30_000,
 	});
-	// crash-isolation: pg-boss's manager emits 'error' on a worker-connection
-	// failure (a proxy-killed idle conn under sustained cross-internet writes).
-	// With NO listener, EventEmitter THROWS on emit('error'), the worker's
-	// promise rejects unhandled, and Bun exits the process — the scala-extract
-	// restart-storm of 2026-07-19. The listener makes it a logged, recovered
-	// event. This is the pg-boss-owned connection, the sibling of @teamscala/db's
-	// application-pool pool.on('error') handler (the app pool alone did not
-	// cover pg-boss's separate pool). Registered before start() so a boot-time
-	// error is caught too.
 	boss.on("error", (err) => {
 		log.warn(`[pg-boss:${ctx.serviceSlug}] recovered error event (process kept alive)`, {
 			error: err instanceof Error ? err.message : String(err),
@@ -165,21 +108,10 @@ export async function mountPgBoss(
 	boss.on("warning", (w) => {
 		log.warn(`[pg-boss:${ctx.serviceSlug}] warning`, { warning: String(w) });
 	});
-	// start() MUST precede work()/schedule() — it opens the DB connection;
-	// calling schedule() before start() crashes the timekeeper with
-	// "Database not opened. Call open() before executing SQL." (pg-boss v12)
 	await boss.start();
-	pgBossInstance = boss;
 
 	for (const entry of scheduledEntries) {
-		// crash-isolation: a malformed scheduled_job row degrades to "this job
-		// unavailable" (logged + event-log row), NEVER a boot-crash. A bare
-		// pg-boss assert reaching boot is the violation.
 		let config: ScheduledJobConfig;
-		// validateRow returns a RESULT WRAPPER ({ok:true,value}|{ok:false,issues}),
-		// never the config itself — measured 2026-09-16: assigning the wrapper as
-		// the config left queue_name/handler_slug undefined and silently skipped
-		// EVERY row on services holding db-validation 0.1.289+.
 		const validated = validateRow("scheduled_job", entry.config);
 		if (!validated.ok) {
 			const reason = validated.issues
@@ -210,19 +142,12 @@ export async function mountPgBoss(
 		const queueName = config.queue_name;
 
 		try {
-			// pg-boss v12 requires the queue to exist before work()/schedule()
-			// dispatch against it ("Queue X does not exist") — createQueue's
-			// underlying SQL is ON CONFLICT DO NOTHING, so calling it on every
-			// boot is a safe idempotent assert, never a duplicate-creation error.
 			await boss.createQueue(queueName);
 			await boss.work(queueName, async (jobs) => {
 				let result: unknown;
 				for (const job of jobs) {
 					result = await resolveHandler(config.handler_slug, config, job.data);
 				}
-				// pg-boss stores the work handler return as job output when
-				// exactly one job was processed (manager.js complete()). For
-				// batch/scheduled jobs the return is not stored.
 				return jobs.length === 1 ? result : undefined;
 			});
 
@@ -260,15 +185,6 @@ export async function mountPgBoss(
 				});
 			}
 
-			// A SUCCESSFUL mount emitted nothing until now, while every failure
-			// path above recorded an event — so the one state you most need to
-			// confirm ("is this job actually scheduled on this service?") was the
-			// only one with no evidence. Combined with resolveHandler THROWING
-			// into boss.work() rather than warning, that made "never scheduled"
-			// and "fired and threw" externally identical, and cost a
-			// scheduled_job relocation that had to be reverted undiagnosed on
-			// 2026-07-30. Emitting on success makes the mount set queryable
-			// (event-log-is-the-only-durable-event-log).
 			const mounted = jobs[jobs.length - 1];
 			recordEvent({
 				kind: "pgboss.job.mounted",
@@ -282,10 +198,6 @@ export async function mountPgBoss(
 				},
 			});
 		} catch (err) {
-			// crash-isolation for the mount path: a work()/schedule() failure
-			// (e.g. DB not open, queue conflict) degrades to "this job unavailable"
-			// (logged + event-log row), NEVER a boot-crash. Same treatment as the
-			// row-validation guard above.
 			const reason = err instanceof Error ? err.message : String(err);
 			log.error(
 				`[pg-boss-mount:${ctx.serviceSlug}] scheduled_job "${entry.slug}" failed to mount (work/schedule) — skipping`,
@@ -299,16 +211,6 @@ export async function mountPgBoss(
 		}
 	}
 
-	// Reconcile orphaned cron schedules: unschedule any pg-boss schedule that no longer corresponds to an ACTIVE registry row. Deactivating/deleting a
-	// scheduled_job (or sync_job_handler) previously left its cron lingering in pgboss.schedule, firing indefinitely — 2 stale web-extractor schedules
-	// found 2026-07-27, still scraping every 3/15min months after the job was meant to be one-off. Deactivation must actually stop the cron. A schedule is
-	// "backed" iff ANY active registry row's slug OR queue_name equals its name — this covers scheduled_job AND sync_job_handler (and any future
-	// schedule-owning type) without hardcoding the type list, so live sync jobs (zoho_assist_sync, trackabi, …) are never touched. Runs on every pg-boss
-	// mount and reconciles GLOBALLY: an orphan is removed regardless of which
-	// service created it, since a cron with no active backing row is drift by
-	// definition. A service with zero active scheduled jobs early-returns above
-	// and never reaches here — scala-loga (7 cron jobs) is the reliable
-	// reconciler, but any service-with-jobs that boots cleans the full set.
 	try {
 		const backedScheduleNames = new Set(
 			allEntries.flatMap((e) => {
@@ -335,9 +237,6 @@ export async function mountPgBoss(
 			});
 		}
 	} catch (err) {
-		// crash-isolation: a reconciliation failure degrades to "orphans not
-		// cleaned this boot" (logged), never a boot-crash — reconciled on the
-		// next successful mount.
 		log.warn(`[pg-boss:${ctx.serviceSlug}] schedule reconciliation failed`, {
 			error: err instanceof Error ? err.message : String(err),
 		});

package/src/proposal-gate.ts

@@ -4,19 +4,13 @@
  */
 
 import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
-import { signAccessToken, verifyAccessToken } from "./content-gate/token.ts";
+import { signAccessToken, verifyAccessToken } from "@teamscala/agreement-generation/content-gate-token";
 import { resolveProposalAuthorizedEmails } from "./proposal-authorized-emails.ts";
 import { propTtlMs } from "./gate-ttls.ts";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import * as v from "valibot";
 
-/**
- * Proposal gate display + behaviour, DB-driven (config/content-gate-proposal),
- * never hardcoded. requireOtp is the per-gate OTP switch (proposals default
- * off — email-only; agreements opt in). A missing/invalid row falls back to the
- * proposal-appropriate defaults so the gate UI ALWAYS renders.
- */
 interface ProposalGateSettings {
 	title: string;
 	subtitle: string;
@@ -78,8 +72,6 @@ function buildGateBlock(
 			gateContextField: "proposalId",
 			gateContextValue: proposalId,
 			gateAction: "/api/proposal-access",
-			// Display + behaviour are DB-driven (config/content-gate-proposal),
-			// not hardcoded. requireOtp is the per-gate OTP switch.
 			title: settings.title,
 			subtitle: settings.subtitle,
 			gateRequireOtp: settings.requireOtp,
@@ -100,26 +92,14 @@ export const proposalGateConfig: ContentGateConfig = {
 		const email = verifyAccessToken(token, PROP_COOKIE, resourceId, nowMs);
 		return email ? { email } : null;
 	},
-	// Baked-in unified auth (engine default): a logged-in viewer whose session
-	// email is in this set (issuing-org team ∪ recipient ∪ partner) is released
-	// with no email/OTP entry. Just exposing the resolver opts this gate into the
-	// platform-wide behaviour — no per-gate session code.
 	resolveAuthorizedEmails: resolveProposalAuthorizedEmails,
 	async onAuthorized(resolved, _resourceId, { email }) {
-		// Seed the verified viewer identity (building-applications initialVisitor).
 		(resolved as { initialVisitor?: { email: string } }).initialVisitor = {
 			email,
 		};
-		// THE ASSISTANT IS NO LONGER INJECTED HERE. It is declared on the
-		// page_route row (`assistant`) and applied once, centrally, after every
-		// gate has run — so the bubble is a setting rather than a line of code
-		// inside one resource type's gate. This call was the reason a third
-		// resource type could not have an assistant without editing service-boot.
 	},
 	async onUnauthorized(resolved, resourceId) {
 		const settings = await loadProposalGateSettings();
-		// Replace the proposal BODY with the gate block — no proposal content
-		// reaches the HTML. Header/footer chrome stays branded.
 		const page = resolved.page as
 			| (PuckHolder & {
 					meta_title?: unknown;
@@ -133,18 +113,11 @@ export const proposalGateConfig: ContentGateConfig = {
 				buildGateBlock(resourceId, brandPrimaryColor(resolved), settings),
 			];
 		}
-		// Neutralize the PAGE record's meta too: page.meta_title/meta_description
-		// feed pageData.meta → the <title>/og tags AND the __PAGE_DATA__ hydration
-		// JSON. Without this the proposal topic + partner name leak via meta even
-		// though the body is withheld (the 2026-06-13 meta-leak: a gated proposal
-		// still exposed "Webinar Campaign · in partnership with <partner>").
 		if (page) {
 			page.meta_title = "Private proposal";
 			page.meta_description = "";
 			page.name = "Private proposal";
 		}
-		// Neutralize the proposal record so the meta_context resolver + any block
-		// reading it can't leak name/partner/cover/recipient.
 		const prop = resolved.proposal as Record<string, unknown> | undefined;
 		if (prop) {
 			prop.name = "Private proposal";
@@ -153,13 +126,6 @@ export const proposalGateConfig: ContentGateConfig = {
 			prop.prepared_for = "";
 			prop.cover_image_url = "";
 		}
-		// Neutralize the resolved headerData too: it carries the recipient's
-		// name (row1Value = prepared_for) and title, resolved during the loader
-		// phase BEFORE this gate ran — without this, __PAGE_DATA__ ships the
-		// recipient name to every unauthorised visitor while the body is
-		// withheld. Labels stay (generic words); values go. Measured 2026-09-03:
-		// the gate floor's hydration payload carried the recipient name to
-		// anonymous visitors on the exact page this outage was about.
 		const headerData = resolved.headerData as Record<string, unknown> | undefined;
 		if (headerData) {
 			headerData.title = "";
@@ -167,12 +133,6 @@ export const proposalGateConfig: ContentGateConfig = {
 			headerData.row2Value = "";
 			headerData.row3Value = "";
 		}
-		// Neutralize the CRM contact record too. The v8 adapter ignores select
-		// (the full record returns), so without this the gate floor's hydration
-		// payload ships the recipient's whole contact row — first/last/full
-		// name, emails, phones, CRM ids — to every unauthorised visitor. The
-		// company fields stay: the header's Organisation row shows the company,
-		// which is brand chrome, not recipient identity.
 		const contact = resolved.contact as Record<string, unknown> | undefined;
 		if (contact) {
 			const keep = new Set(["id", "company_id", "company_name", "company_website"]);

package/src/quiz-gate.ts

@@ -4,21 +4,13 @@
  */
 
 import type { AccessConfig, ContentGateConfig } from "./content-gate/config-types.ts";
-import { signAccessToken, verifyAccessTokenIdentity } from "./content-gate/token.ts";
+import { signAccessToken, verifyAccessTokenIdentity } from "@teamscala/agreement-generation/content-gate-token";
 import { quizTtlMs } from "./gate-ttls.ts";
 
 const QUIZ_COOKIE = "quiz_token";
-/**
- * The ENTRY MARKER: proves this request is the redirect the identity submit
- * produced, not a later load. Operator ruling 2026-09-14: a refresh must return
- * to the identity gate — the visitor starts at Name/Email on every fresh load,
- * and only the submit's own redirect releases the quiz. The marker is set by
- * the access endpoint with the token and cleared by the render it authorized.
- */
 const QUIZ_ENTRY_COOKIE = "quiz_token_entered";
 const QUIZ_ACCESS_PATH = "/api/quiz-access";
 
-/** The assessment this page is for, from the quiz-with-brand loader's graph. */
 function quizId(resolved: Record<string, unknown>): string {
 	const quiz = resolved.quiz as { id?: unknown } | null | undefined;
 	return typeof quiz?.id === "string" ? quiz.id : "";

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

@@ -3,17 +3,6 @@
  * @status handwritten
  */
 
-		// REFUSE, DO NOT SKIP. `existsSync(routerPath)` being false used to fall straight through with appRouter=null and still register a client + log
-		// success. That client carries only the three platform routers below and NO CRUD models, which is indistinguishable from a healthy one until a
-		// page asks it for a model — at which point resolve-from-loader-config throws MissingLoaderModelCapabilityError, far from the actual fault.
-		//
-		// Measured 2026-08-20: scala-quiz and scala-forms served 500s on every data-backed page while /health returned 200 and this line logged "ORPC
-		// serverClient registered". The build had produced no generated router (its railpack.json ran registry codegen against an unreachable
-		// *.railway.internal host), and nothing anywhere said so.
-		//
-		// A service whose service_schema DECLARES models and has no generated router is not degraded, it is non-functional — so this fails the boot
-		// 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.
 
 import { join } from "node:path";
 import { getAppLogger } from "@teamscala/logger/app-loggers";
@@ -31,16 +20,6 @@ export async function registerPageServerClient(
 		};
 		const { createRouterClient } = await import("@orpc/server");
 		const { getPrisma } = await import("@teamscala/db/prisma-registry");
-		// Load the composed CRUD router via getAppRouter() — the SAME registered
-		// instance the /api/rpc mount uses (mount-orpc-router.ts). The previous code
-		// did a raw second `import(cwd + "prisma/generated/orpc/routers/index.ts")`,
-		// re-loading the generated routers under a different module specifier than
-		// the mount already used; in the full boot process that re-execution throws,
-		// and the throw was swallowed by a SILENT catch — leaving the page-server
-		// client without the CRUD models, so every data-backed page 500s
-		// ("client.<model> is undefined", the scala-sign prod outage). existsSync
-		// gates the legitimate no-router case (daemon/portal services that own no DB
-		// schema) so it stays a clean skip, never a misleading warn.
 		const { existsSync } = await import("node:fs");
 		const routerPath = join(
 			process.cwd(),
@@ -52,8 +31,6 @@ export async function registerPageServerClient(
 				const { getAppRouter } = await import("@teamscala/orpc/app-router");
 				appRouter = ((await getAppRouter()) as Record<string, unknown>) ?? null;
 			} catch (err) {
-				// A genuine load failure here means every data-backed page 500s, so it
-				// must surface, never be swallowed (protective-layers-fail-explicitly).
 				log.warn(
 					`[scala-install:${serviceSlug}] appRouter load failed — data-backed pages will 500: ${err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err)}`,
 				);
@@ -61,28 +38,6 @@ export async function registerPageServerClient(
 		}
 		const declaredModels = await (async (): Promise<string[]> => {
 			const capSlug = toCapabilitySlug(serviceSlug);
-			// LOOK IT UP BY CAPABILITY, NOT BY DEPLOYABLE NAME. A service_schema
-			// row describes the APPLICATION's data surface, so there is ONE row
-			// for both lanes; the dev lane arrives here as
-			// `scala-projects-bun-dev`. Both sides normalize through
-			// toCapabilitySlug, so the join is tier-agnostic by construction.
-			// See ./capability-slug.ts.
-			//
-			// READ WITH THE REAL SCHEMA, NOT `undefined`. The previous call passed
-			// `undefined as never`, so v.parse(undefined, raw) threw a TypeError
-			// (schema is not a schema) on EVERY service, the bare catch below turned
-			// that into "declares nothing", and the refusal at the bottom NEVER
-			// fired — a service declaring 18 models booted "0 declared model(s)"
-			// and served 500s. (measured scala-sign 2026-09-24/25: row declares 18,
-			// boot logged 0.) loadOptionalRegistryConfig parses against
-			// ServiceSchemaConfigSchema and returns null ONLY for a missing row.
-			//
-			// A MISSING ROW is legitimately "declares nothing" (daemon/portal
-			// shells own no DB models) and passes through clean. A READ FAILURE is
-			// NOT "declares nothing" — it fails the boot naming the error, so the
-			// database can never quietly become "no models" and let a router-less,
-			// data-backed service boot and serve 500s
-			// (`a-component-may-not-report-a-state-it-has-not-verified`).
 			const { loadOptionalRegistryConfig } = await import(
 				"@teamscala/db/registry/load-config"
 			);
@@ -133,8 +88,6 @@ export async function registerPageServerClient(
 		const { PlatformIdentitySchema } = await import(
 			"@teamscala/db-validation/registry-schemas/platform-identity"
 		);
-		// Platform org id is a registry value (registries-are-source-of-truth),
-		// not a hardcoded literal — read from config/platform-identity.
 		const platformIdentity = await loadRegistryConfig(
 			"config",
 			"platform-identity",
@@ -154,19 +107,13 @@ export async function registerPageServerClient(
 			} as never,
 		);
 		mod.setServerClient(client);
-		// Record declared-vs-present capability for /health. Property lookups only.
 		(mod as unknown as { recordServerClientCapability?: (m: readonly string[]) => void })
 			.recordServerClientCapability?.(declaredModels);
-		// State the model count. "registered" alone was true in the outage and told
-		// nobody anything; a zero here is now visible in the boot log.
 		log.info(
 			`[scala-install:${serviceSlug}] ORPC serverClient registered (system:super-admin) — ` +
 				`${Object.keys(composed).length} router(s), ${declaredModels.length} declared model(s)`,
 		);
 	} catch (err) {
-		// RETHROW. Swallowing this into a warn is what let a service boot, pass its
-		// healthcheck and serve 500s on every page. The boot must fail so the
-		// supervisor and the deploy healthcheck can see it.
 		log.error(
 			`[scala-install:${serviceSlug}] serverClient registration FAILED — data-backed pages cannot render: ${err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err)}`,
 		);

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

@@ -2,27 +2,9 @@
  * @system service-boot
  * @status handwritten
  */
-/**
- * SSR-prefetch the signed-in user's AI-chat conversation so a CLICK-opened AI
- * panel renders the real conversation on first paint — never a loading gate
- * (ssr-then-live-handoff). The AiChat block lives on the /ai PANEL page, which
- * isn't rendered when the panel is closed, so its block serverLoader can't run
- * at page-load; this prefetches server-side (regardless of panel open-state) +
- * stamps pageData.aiChatSession, which AiChat reads on mount. The agent is
- * resolved from the /ai panel page's own AiChat block (single source of truth —
- * no duplicate config to drift). Fired in parallel with the post-processors +
- * bounded by their window; a failure degrades silently to the client-side
- * createOrRestore fallback, never an error page.
- */
 
 import { getServerClient } from "../page-server-orpc/server-client.ts";
 
-/**
- * Deep-find the serving `website_id` in the loader graph (resolved). The
- * Utility/Portal shell carries the website id (not a slug) under a loader
- * source key; the client RegionPageSwap reads it from loaderData.*.website_id
- * the same way. Bounded walk (cycle-safe) over the resolved loader results.
- */
 function findWebsiteId(root: unknown): string | undefined {
 	if (!root || typeof root !== "object") return undefined;
 	const seen = new Set<unknown>();

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

@@ -3,64 +3,8 @@
  * @status handwritten
  */
 
-/**
- * /sign-in brand override: a shared org-scoped link 302→/sign-in for the
- * unauthed crawler (WhatsApp), which saw the service's default website
- * brand (the platform owner). The callbackURL carries the destination org
- * — override resolved.brand (before the title/meta/og are built from it)
- * so the page reflects the org the visitor is signing in to. Scoped to
- * /sign-in; resource pages keep their own brand.
- *
- * The org is segment 1 of the canonical portal shape /<websiteId>/<orgId>/
- * <path>, NOT segment 0 (the website id): reading segment 0 fed a website id
- * into fetchOrganisationPageBranding, which resolved no org and left the
- * default (super-admin) brand — the cross-tenant mis-branding this override
- * exists to prevent (portal-branding-resolves-page-org-first, 2026-07-21).
- * Shared helper so this and bind-page-handler cannot drift on the answer.
- */
 
-/**
- * brand-is-org-owned-full-scheme, reconciled with page-org-first
- * (portal-branding-resolves-page-org-first): the session override now
- * personalizes ONLY platform pages (page org === website owning-org).
- * Tenant pages keep their resolved page-org brand — the page is
- * authoritative, the menu switcher changes which tenant's pages you
- * view. Anonymous/public (no session) keeps the resolved brand. Same
- * fetchOrganisationPageBranding pattern as the /sign-in brand override.
- *
- * A PUBLIC PAGE IS NEVER PERSONALISED TO THE READER'S ORG. Personalising
- * the brand is right for a portal — you are looking at your own
- * workspace. It is wrong for a public document, which belongs to the org
- * that PUBLISHED it and must look identical to every reader.
- *
- * Measured 2026-08-17: the Launcha Authority Blueprint, owned by GMG
- * APAC, rendered correctly for an anonymous customer and in GBG Indo's
- * navy with the scala logo for any signed-in staff member — so the two
- * people checking it before it went to clients were the only two who
- * could not see what a client sees. Silent, and inverted: the reviewers
- * got the wrong page.
- */
 
-/**
- * BRAND FROM THE ORG THAT OWNS THE RESOURCE, not the website's owner.
- * A public resource page (an assessment report, a shared document) is
- * hosted on a shared website but BELONGS to a tenant. resolvePageBrand
- * reads pageData.orgId, which is the WEBSITE's org, so every tenant's
- * report rendered the host org's logo and palette.
- *
- * Measured 2026-08-17: the Launcha Authority Blueprint is owned by GMG
- * APAC (#FF4500, launcha logo) and rendered with GBG Indo's navy and
- * scala mark, because both pages live on the shared "Public Pages"
- * site. The loader had already resolved the right org — nothing
- * consumed it.
- *
- * `brand_org_path` names where the owning org id lives in the resolved
- * loader data (e.g. "quiz.organisation_id"), so which resource owns the
- * brand is a ROW, never a per-service branch
- * (`business-logic-is-rows-plus-executors`). Absent or unresolvable,
- * the website's org stands — this can only ever narrow the brand to a
- * more specific owner, never blank it.
- */
 
 import { fetchOrganisationPageBranding } from "@teamscala/db/fetch-organisation-page-branding";
 import { getPlatformOrgId } from "@teamscala/db/registry/platform";
@@ -77,9 +21,6 @@ function spreadBranding(
 	return {
 		...existing,
 		companyName: branding.company_name,
-		// Friendly name is the customer-facing one; falling back to the
-		// legal entity fed "GMG APAC" to every consumer that correctly
-		// read companyFriendlyName (e.g. logoAlt in the Puck host codegen).
 		companyFriendlyName:
 			branding.company_friendly_name ?? branding.company_name,
 		primaryColor: branding.brand_primary_color ?? existing?.primaryColor,
@@ -117,7 +58,6 @@ export async function applySignInBrandOverride(
 			}
 		}
 	} catch {
-		// Branding fetch failed — keep the default brand (no regression).
 	}
 }
 
@@ -131,31 +71,9 @@ export async function applySessionOrgBranding(
 		renderMode !== "public" &&
 		sessionOrgId &&
 		sessionOrgId !== (pageData.orgId as string | undefined) &&
-		// Page-org-first (portal-branding-resolves-page-org-first): the
-		// session override personalizes ONLY the shared PLATFORM website
-		// (super-admin org). A TENANT-owned site (a customer GPT/quiz/portal)
-		// keeps its page-org brand regardless of the viewer session org. The
-		// old pageData.orgId===website.org mis-fired for a tenant whose page org equals their own website org.
 		platformOrgId ===
 			((pageData.website as { organisation_id?: string | null } | undefined)
 				?.organisation_id ?? undefined) &&
-		// ...AND the PAGE itself must be platform-owned. A platform-owned
-		// WEBSITE also hosts tenant DOCUMENTS — an agreement, a proposal, a
-		// signed contract — and those belong to the org that published them.
-		// Testing only the website let the viewer's own org repaint a tenant
-		// document, which is the same defect this rule already fixed once at
-		// the website level (2026-08-17, the Launcha Authority Blueprint).
-		//
-		// It recurred on sign.scala.business, whose website IS owned by the
-		// platform org (c503629a), so the website test passed and every
-		// signed-in staff viewer saw a GMG APAC agreement painted in their own
-		// org's brand — while an anonymous client saw it correctly. That is
-		// the worst possible shape: the only people who cannot see what the
-		// client sees are the people reviewing it before it is sent.
-		//
-		// A public document belongs to the org that PUBLISHED it and must look
-		// identical to every reader, so a page whose org is not the platform's
-		// is never personalised.
 		platformOrgId === (pageData.orgId as string | undefined)
 	) {
 		try {
@@ -169,7 +87,6 @@ export async function applySessionOrgBranding(
 				pageData.brand = spreadBranding(existing, branding);
 			}
 		} catch {
-			// Branding fetch failed — keep the default brand (no regression).
 		}
 	}
 }
@@ -193,12 +110,6 @@ export async function applyBrandOrgPath(
 		}
 		if (typeof cursor === "string" && cursor.length > 0) {
 			pageData.orgId = cursor;
-			// orgId alone is not enough. resolvePageBrand fills only the
-			// accent/secondary/muted gaps from the org; primaryColor, logo and
-			// companyName come from pageData.brand, which was built from the
-			// website's org. Replace those too, the same way the session
-			// override above does, or the page keeps the host's logo while
-			// claiming the tenant's org.
 			try {
 				const owner = await fetchOrganisationPageBranding(
 					getServerClient() as never,
@@ -209,7 +120,6 @@ export async function applyBrandOrgPath(
 					pageData.brand = spreadBranding(existing, owner);
 				}
 			} catch {
-				// Branding fetch failed — keep the website brand (no regression).
 			}
 		} else {
 			log.warn(

package/src/register-registry-page-route/captured-loader-config.ts

@@ -3,7 +3,6 @@
  * @status handwritten
  */
 
-/** Structural slice of the ResourceLoaderConfigSchema output this unit reads. */
 interface LoaderConfigSlice {
 	sources?: { key: string }[];
 	region_slots?: string[];

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

@@ -2,23 +2,6 @@
  * @system service-boot
  * @status handwritten
  */
-/**
- * Stale-while-revalidate read of a cached loader graph.
- *
- * - Fresh hit (within ttlMs): return the cached graph, no refresh.
- * - Stale hit (within ttlMs + staleTtlMs): return the cached graph AND fire ONE
- *   background refresh via cache.refreshInBackground — single-flight (deduped
- *   against the cache's in-flight map), never rejects, leaves the stale entry in
- *   place on failure. The caller deep-clones the returned value before use.
- * - Miss (past staleTtlMs, or never cached): return undefined — the caller
- *   resolves synchronously and cache.set()s the clone.
- *
- * The refresh callback must return a graph safe to store. To SKIP caching a
- * refresh result (e.g. a primary-missing / dead-link graph that must stay
- * per-request so a just-created record appears immediately), the callback THROWS
- * — refreshInBackground catches it, leaves the stale entry, and logs one line
- * (an observable dead-link signal, not a hard error).
- */
 
 import { createCache } from "@teamscala/cache/create-cache";
 

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

@@ -2,25 +2,6 @@
  * @system service-boot
  * @status handwritten
  */
-/**
- * THE ONE SUBJECT DERIVATION. What a page is ABOUT — the entity whose name the
- * browser tab should carry.
- *
- * This existed as THREE hand-written `||` chains, one per render branch in
- * resolve-page-data, and they had already diverged: two ordered form before
- * proposal, the third ordered proposal first. So which resource named the page
- * depended on which branch happened to render it, silently.
- *
- * The divergence is the cheap half of the cost. The expensive half is that a
- * correction has to be applied three times to work, and applying it twice looks
- * exactly like applying it correctly — measured 2026-08-17, when a fix to the
- * quiz subject was shipped, installed and verified present in the bundle while
- * the page kept its old title, because the branch that rendered it held the
- * second copy.
- *
- * One chain, one precedence, one place to change. Adding a resource type is an
- * edit here rather than a fourth branch in three files.
- */
 
 import { interpolateMeta } from "@teamscala/resolver-engine/loader-config/resolve-from-loader-config";
 
@@ -32,11 +13,6 @@ export function buildMetaFromContext(
 	return interpolateMeta(metaContext as Record<string, unknown>, resolved);
 }
 
-/**
- * The page's own meta_title row (loaderData.page first, resolved.page second)
- * — used only on /sign-in, where the org's sign-in page title overrides the
- * derived one. Moved from register-registry-page-route.ts.
- */
 export function resolvePageMetaTitle(
 	resolved: Record<string, unknown>,
 ): unknown {