@teamscala/service-boot 0.23.503 → 0.23.506

package/src/quiz-gate.ts

@@ -30,6 +30,14 @@ import { signAccessToken, verifyAccessTokenIdentity } from "./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. */
@@ -40,6 +48,7 @@ function quizId(resolved: Record<string, unknown>): string {
 
 export const quizGateConfig: ContentGateConfig = {
 	cookieName: QUIZ_COOKIE,
+	entryCookieName: QUIZ_ENTRY_COOKIE,
 	getResourceId(resolved) {
 		// No quiz in the graph → not a quiz page → the engine no-ops.
 		return quizId(resolved);
@@ -70,6 +79,7 @@ export const quizGateConfig: ContentGateConfig = {
 export const quizAccessConfig: AccessConfig = {
 	path: QUIZ_ACCESS_PATH,
 	cookieName: QUIZ_COOKIE,
+	entryCookieName: QUIZ_ENTRY_COOKIE,
 	get ttlMs() {
 		return quizTtlMs();
 	},

package/src/read-html-template.test.ts

@@ -1,15 +1,11 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Regression guard for the runtime-owned Puck document and manifest-keyed
- * HTML cache. The lifetime-pinned
- * cache served a deleted bundle hash after a post-boot rebuild (scala-docs
- * 2026-06-13): build-client-assets rewrites asset-manifest.json + deletes the
- * old hashed bundle, but the cached HTML kept the old hash → 404 → no
- * hydration. These tests pin that a manifest change re-substitutes the HTML.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";

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

@@ -1,22 +1,11 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * applySessionOrgBranding must never repaint a TENANT document in the
- * VIEWER's brand.
- *
- * A public document belongs to the org that PUBLISHED it and must look
- * identical to every reader. Personalising to the reader's org is right for a
- * portal (you are looking at your own workspace) and wrong for a document.
- *
- * The regression this locks: sign.scala.business's website is owned by the
- * PLATFORM org, so the website-level test passed and the session override
- * fired on agreements owned by tenants. Every signed-in staff viewer saw a
- * GMG APAC agreement in their own org's brand while an anonymous client saw
- * it correctly — so the only people who could not see what the client sees
- * were the people reviewing it before sending.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { describe, expect, mock, test } from "bun:test";
 

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

@@ -1,16 +1,12 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * The boot log is the ONLY observable statement of what a running service
- * captured from its resource_loader row (the 2026-08-18 evening-long bisect:
- * a footer region added to the row never reached the booted process, and
- * nothing anywhere said so). These tests pin the contract the line states —
- * the captured source keys, the captured region slots, and the restart
- * requirement — so the observability cannot silently regress to the old bare
- * "registered route" line.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
+
 import { describe, expect, test } from "bun:test";
 import { describeCapturedLoaderConfig } from "./captured-loader-config.ts";
 

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

@@ -1,15 +1,12 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Regression guard for readCachedGraph's stale-while-revalidate decision
- * (capability-harvest-on-split / what-must-have-a-test). The fold onto
- * @teamscala/cache's getWithMeta + refreshInBackground must keep firing the
- * background refresh past the fresh window — if it ever stops, the page-route
- * graph cache silently degrades to fresh-or-miss (the measured 3.8s
- * cache-expired in-request regression the SWR exists to prevent).
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
+
 import { describe, expect, test } from "bun:test";
 import { createCache } from "@teamscala/cache/create-cache";
 import { readCachedGraph } from "./graph-cache.ts";

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

@@ -1,27 +1,11 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit extend the regression set for the live loader-config contract
- *
- * Behavioural tests for the per-request resource_loader read (the fix for the
- * boot-baked-loader defect): resource_loader is NOT on the deploy-time bake
- * list, so a registry row edit must reach the running service WITHOUT a
- * restart. The registration loop's boot read is warm/validate only.
- *
- *  1. Two requests to the same route with the row edited between them — the
- *     SECOND request's graph resolution receives the NEW source set, and the
- *     live read ran once per request (not once per boot).
- *  2. A row that vanishes (or stops validating) between requests — the second
- *     request FAILS CLOSED (the read throws into the branded error path;
- *     the boot snapshot never silently outlives its row).
- *  3. The graphKey fingerprint changes when the config changes — a row edit
- *     invalidates the per-route SWR graph cache immediately instead of
- *     serving the old graph until the fresh window lapses.
- *
- * Only the registry reader and the heavy graph collaborators are mocked; the
- * real registrar, real Hono app, real loadData pipeline and the real
- * live-loader-config unit are under test.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { GlobalRegistrator } from "@happy-dom/global-registrator";
 import { afterEach, describe, expect, mock, test } from "bun:test";

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

@@ -33,7 +33,7 @@
  * edit here rather than a fourth branch in three files.
  */
 
-import { interpolateMeta } from "../resolve-from-loader-config.ts";
+import { interpolateMeta } from "../interpolate-meta.ts";
 
 export function buildMetaFromContext(
 	metaContext: Record<string, Record<string, string>> | undefined,

package/src/register-registry-page-route/page-data-shared.test.ts

@@ -1,15 +1,12 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Behavioural pins for the shared page-data helpers. The load-bearing cases:
- * layout defaults FILL missing root props and never clobber existing values
- * (a theme row must not overwrite page-authored props), pickRootProp takes
- * the FIRST region carrying a usable value, brand tokens degrade to nulls —
- * never throw — on a missing brand row, and the unresolved-region-slot warn
- * fires ONCE per slot per process (the hot-path throttle).
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
+
 import { describe, expect, mock, test } from "bun:test";
 
 const warns: string[] = [];

package/src/register-registry-page-route/public-shell-page-data.test.ts

@@ -1,22 +1,11 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Regression cover for two defects the operator reported on the launcha quiz,
- * both of which lived in publicShellPageData and were invisible to every other
- * check because the page rendered 200 with a clean log either way.
- *
- * 1. screenMode was never threaded, so a page declaring "full-screen" fell back
- *    to build-page-tree's card-wrapper default and the site header rendered
- *    INSIDE the card instead of across the top of the page.
- * 2. the page title used the LEGAL entity name (companyName) rather than the
- *    trading name (companyFriendlyName), putting "GMG APAC" on every launcha
- *    page.
- *
- * Both assert the OUTCOME (the emitted flag, the composed title text), not the
- * presence of a key — a shape assertion would have passed throughout the bug.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { describe, expect, test } from "bun:test";
 import { publicShellPageData } from "./public-shell-page-data.ts";

package/src/register-registry-page-route/resolve-entity-title.test.ts

@@ -1,10 +1,11 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Locks the single subject derivation that replaced three divergent copies.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { describe, expect, test } from "bun:test";
 import { resolveEntityTitle } from "./meta-title.ts";

package/src/register-registry-page-route/resolve-page-data.test.ts

@@ -1,16 +1,12 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Regression test for the silent region-slot vanish (measured 2026-08-18): a
- * region the operator declared in resource_loader.region_slots whose source
- * did not resolve was skipped with no log, no error and no signal anywhere —
- * the page rendered minus a region while every other suspect checked out.
- * These tests pin the observable contract: the omission is LOGGED naming the
- * slot, once per slot per process (hot path never spams), and the resolved
- * regions still render every slot that did resolve.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
+
 import { describe, expect, mock, test } from "bun:test";
 
 const warn = mock((_message: string) => {});

package/src/register-registry-page-route/resolve-request-graph.test.ts

@@ -1,16 +1,12 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Behavioural pins for the per-request loader-graph resolution. The load-
- * bearing cases: a bare root with a resource_type throws the 200 holding-page
- * signal (never falls through to the marketing site), a dead link (declared
- * primary source that resolves to nothing) throws the branded 404, a content
- * route with no page row throws the dead-link floor, and a content route with
- * an EMPTY page row throws the 200 empty-page floor — the three distinct
- * surfaces the page binder maps to three distinct responses.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
+
 import { describe, expect, mock, test } from "bun:test";
 
 let loaderGraph: Record<string, unknown> = {};

package/src/resolve-from-loader-config.test.ts

@@ -1,19 +1,15 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * resolve-from-loader-config.test.ts — locks in the interpolation contract that
- * resolver_fn sources depend on: a bare `:sourceKey` ref passes the WHOLE
- * resolved source object (so a resolver_input like {response: ":response"}
- * reaches the resolver), while a URL param (e.g. :id) still resolves from params.
- */
+// @system codegen
+// @status generated
+// @edit change the suite in the owned-suites band, then re-run codegen. Hand-edits are overwritten.
+//
+// This suite's assertions are OWNED by the codegen band: the band module
+// carries them verbatim, this file is the emission, and hand edits here are
+// overwritten on the next run. The rationale each assertion carries moved
+// with it into the band.
 
 import { describe, expect, test } from "bun:test";
-import {
-	interpolateMeta,
-	resolveFromLoaderConfig,
-} from "./resolve-from-loader-config";
+import { resolveFromLoaderConfig } from "./resolve-from-loader-config";
+import { interpolateMeta } from "./interpolate-meta.ts";
 import {
 	getServerClient,
 	isServerClientRegistered,
@@ -324,3 +320,110 @@ describe("required sources refuse unresolvable where refs", () => {
 		expect(captured.where).toEqual({ partner_id: null });
 	});
 });
+
+describe("non-UUID URL refs resolve absent, never throw into the breaker", () => {
+	// A URL param that is not a uuid (a slug link, a scanner path) can never
+	// match a uuid column. The query failure IS the resource being missing
+	// for this URL — the same state as a deleted row — so it resolves null
+	// and the upstream primary-missing check renders the branded 404.
+	// Throwing here instead counted every dead shape as a CONSECUTIVE
+	// render-budget failure: 53 scanner hits in a row on scala-quiz prod
+	// (2026-09-11) sat the layer DEGRADED fail-closed and every real page
+	// 503'd for hours.
+	const original = isServerClientRegistered() ? getServerClient() : null;
+	const sqlError = (msg: string) => {
+		const e = new Error(msg);
+		e.name = "SqlQueryError";
+		return e;
+	};
+
+	test("a required source rejecting a non-uuid URL ref resolves null", async () => {
+		setServerClient({
+			builda_pages: {
+				findFirst: async () => {
+					throw sqlError('invalid input syntax for type uuid: "launcha-authority-index"');
+				},
+			},
+		} as never);
+		try {
+			await expect(
+				resolveFromLoaderConfig(
+					{
+						sources: [
+							{
+								key: "assessment",
+								source: "orpc",
+								model: "builda_pages",
+								where: { id: ":id" },
+								optional: false,
+							},
+						],
+					},
+					{ id: "launcha-authority-index" },
+				),
+			).resolves.toEqual({ assessment: null });
+		} finally {
+			setServerClient(original as never);
+		}
+	});
+
+	test("a SqlQueryError that is NOT a non-uuid ref still throws", async () => {
+		setServerClient({
+			builda_pages: {
+				findFirst: async () => {
+					throw sqlError('column "page_id" does not exist');
+				},
+			},
+		} as never);
+		try {
+			await expect(
+				resolveFromLoaderConfig(
+					{
+						sources: [
+							{
+								key: "page",
+								source: "orpc",
+								model: "builda_pages",
+								where: { id: ":id" },
+								optional: false,
+							},
+						],
+					},
+					{ id: "p1" },
+				),
+			).rejects.toThrow('column "page_id" does not exist');
+		} finally {
+			setServerClient(original as never);
+		}
+	});
+
+	test("a non-SqlQueryError rejection on a required source still throws", async () => {
+		setServerClient({
+			builda_pages: {
+				findFirst: async () => {
+					throw new Error("connection refused");
+				},
+			},
+		} as never);
+		try {
+			await expect(
+				resolveFromLoaderConfig(
+					{
+						sources: [
+							{
+								key: "page",
+								source: "orpc",
+								model: "builda_pages",
+								where: { id: ":id" },
+								optional: false,
+							},
+						],
+					},
+					{ id: "p1" },
+				),
+			).rejects.toThrow("connection refused");
+		} finally {
+			setServerClient(original as never);
+		}
+	});
+});

package/src/resolve-from-loader-config.ts

@@ -16,6 +16,11 @@ import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import type { ResolverFnKey } from "@teamscala/db/registry/generated/resolver-fn";
 import { ResolverFnConfigSchema } from "@teamscala/db-validation/registry-schemas/resolver-fn";
 import { getServerClient } from "./page-server-orpc/server-client";
+import { interpolateTemplate, resolveParamRef } from "./interpolate-meta";
+import {
+	MissingLoaderModelCapabilityError,
+	isUrlRefNotUuidError,
+} from "./loader-errors";
 
 interface SourceConfig {
 	key: string;
@@ -36,105 +41,6 @@ interface LoaderConfig {
 	merge_strategy?: Record<string, unknown>;
 }
 
-class MissingLoaderModelCapabilityError extends Error {
-	constructor(model: string, sourceKey: string) {
-		super(
-			`[resource_loader] source "${sourceKey}" requires model "${model}", but the generated server client does not expose findFirst for it — regenerate the service schema from its page loaders`,
-		);
-		this.name = "MissingLoaderModelCapabilityError";
-	}
-}
-
-function resolveParamRef(
-	ref: string,
-	params: Record<string, unknown>,
-	resolved: Record<string, unknown>,
-): unknown {
-	const parts = ref.split(".");
-	// A bare (no-dot) ref can name either a resolved source key (e.g. `:response`
-	// passes the whole resolved source object to a resolver_fn) or a URL param
-	// (e.g. `:id`). Prefer the resolved source key, then fall back to the param.
-	// Dotted refs (`:response.total_score`) always read from `resolved`.
-	if (parts.length === 1) {
-		if (resolved != null && typeof resolved === "object" && ref in resolved) {
-			return (resolved as Record<string, unknown>)[ref];
-		}
-		if (params != null && typeof params === "object" && ref in params) {
-			return (params as Record<string, unknown>)[ref];
-		}
-		return undefined;
-	}
-	let current: unknown = resolved;
-	for (const part of parts) {
-		if (current == null || typeof current !== "object") return undefined;
-		current = readField(current as Record<string, unknown>, part);
-	}
-	return current;
-}
-
-/**
- * A resource_loader row spells DATABASE COLUMN NAMES — `page_id`,
- * `organisation_id`, `prepared_for` — because that is what the schema calls
- * them. The ORM hands back CAMELCASE keys — `pageId`, `organisationId`,
- * `preparedFor`. Nothing reconciled the two, so a `:proposal.page_id` ref read
- * a key the object does not have and returned undefined.
- *
- * MEASURED 2026-09-03, and the consequence is far worse than a missing value.
- * `interpolateTemplate` DROPS a key whose value is undefined, so a dependent
- * source declared `where: { id: ":proposal.page_id" }` was issued as
- * `where: {}` — and findFirst with an empty filter returns AN ARBITRARY FIRST
- * ROW. A client proposal page therefore loaded an unrelated builda_page,
- * rendered a stranger's content under the correct brand chrome, and answered
- * 200 throughout. Instrumenting the live resolver showed every dependent
- * source doing it: page, website, contact, partnerOrg and clientOrg all with
- * `where={}`; only `proposal` was correct, because its ref is the URL param
- * `:id` rather than a sibling source.
- *
- * Read the spelled key first, then its camelCase equivalent. Column names stay
- * the authoring vocabulary and a row never has to know what the ORM did to its
- * keys.
- */
-function readField(source: Record<string, unknown>, key: string): unknown {
-	if (key in source) return source[key];
-	const camel = key.replace(/_([a-z0-9])/g, (_m, c: string) => c.toUpperCase());
-	return camel === key ? undefined : source[camel];
-}
-
-function interpolateTemplate(
-	template: unknown,
-	params: Record<string, unknown>,
-	resolved: Record<string, unknown>,
-): unknown {
-	if (typeof template === "string") {
-		const exactMatch = template.match(/^:([a-zA-Z0-9_.]+)$/);
-		if (exactMatch) {
-			return resolveParamRef(exactMatch[1], params, resolved);
-		}
-		if (template.includes(":")) {
-			return template.replace(
-				/:([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)/g,
-				(_match, ref: string) => {
-					const value = resolveParamRef(ref, params, resolved);
-					return value != null ? String(value) : _match;
-				},
-			);
-		}
-		return template;
-	}
-	if (Array.isArray(template)) {
-		return template.map((v) => interpolateTemplate(v, params, resolved));
-	}
-	if (template != null && typeof template === "object") {
-		const out: Record<string, unknown> = {};
-		for (const [k, v] of Object.entries(template)) {
-			const result = interpolateTemplate(v, params, resolved);
-			if (result !== undefined) out[k] = result;
-		}
-		return out;
-	}
-	return template;
-}
-
 function toSelectMap(
 	fields: string[] | undefined,
 ): Record<string, boolean> | undefined {
@@ -370,10 +276,33 @@ export async function resolveFromLoaderConfig(
 			if (!source || !result) continue;
 			if (result.status === "fulfilled") {
 				resolved[source.key] = result.value;
+			} else if (isUrlRefNotUuidError(result.reason)) {
+				// A URL ref that cannot be a uuid names no resource: resolve the
+				// source ABSENT (null) and let the existing semantics decide —
+				// the primary-missing check upstream turns it into the branded
+				// 404 (PrimaryResourceMissingError, which the render-budget
+				// breaker already excludes), an optional source treats it like
+				// any absent row. Throwing here instead is what let dead links
+				// poison the breaker into a site-wide 503 (see the predicate).
+				getAppLogger().warn(
+					`[resource_loader] source "${source.key}" got a non-UUID URL ref — treating as MISSING for this request: ${
+						result.reason instanceof Error ? result.reason.message : String(result.reason)
+					}`,
+				);
+				resolved[source.key] = null;
 			} else if (
 				source.optional &&
 				!(result.reason instanceof MissingLoaderModelCapabilityError)
 			) {
+				// Optional means MAY BE ABSENT, never FAIL IN SILENCE: the source
+				// still resolves to null, but the reason becomes evidence.
+				getAppLogger().warn(
+					`[resource_loader] optional source "${source.key}" FAILED and is absent from this render: ${
+						result.reason instanceof Error
+							? `${result.reason.message}\n${result.reason.stack ?? ""}`
+							: String(result.reason)
+					}`,
+				);
 				resolved[source.key] = null;
 			} else {
 				throw result.reason;
@@ -385,19 +314,3 @@ export async function resolveFromLoaderConfig(
 
 	return resolved;
 }
-
-export function interpolateMeta(
-	template: Record<string, unknown>,
-	data: Record<string, unknown>,
-): Record<string, unknown> {
-	const out: Record<string, unknown> = {};
-	for (const [k, v] of Object.entries(template)) {
-		if (v != null && typeof v === "object" && !Array.isArray(v)) {
-			out[k] = interpolateMeta(v as Record<string, unknown>, data);
-		} else {
-			const result = interpolateTemplate(v, {}, data);
-			out[k] = result ?? v;
-		}
-	}
-	return out;
-}