@teamscala/service-boot 0.23.503 → 0.23.505

package/src/handlers/platform-fault-escalation.test.ts

@@ -1,13 +1,12 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Unit tests for the pure decision core of the platform-fault escalation
- * sweep (`platform-fault-escalation` handler). The handler's DB/WhatsApp I/O
- * is runtime-verified by the scheduled_job firing; this locks the threshold,
- * dedup and episode semantics from the 2026-08-15 incident brief.
- */
+// ! @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 {
 	composeEscalationMessage,

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

@@ -1,3 +1,12 @@
+// ! @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 { join } from "node:path";
 

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

@@ -1,3 +1,12 @@
+// ! @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 { join } from "node:path";
 

package/src/handlers/whatsapp-liveness-handler.test.ts

@@ -1,15 +1,12 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Handler-level integration test for `pollWhatsAppLiveness`: mocks the central
- * /mcp forwarder (`forwardToolToCentralMcp`) + recordEvent, drives a
- * connected→disconnected transition across two polls, and asserts the
- * `messaging.whatsapp.device.disconnected` recordEvent fires — the "simulated
- * disconnect emitting recordEvent" of `whatsapp-remote-logout-monitor`, without
- * touching the real device or the real /mcp.
- */
+// ! @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 { beforeEach, expect, mock, test } from "bun:test";
 
 const recordEventCalls: Array<{ kind: string; payload: Record<string, unknown> }> = [];

package/src/handlers/whatsapp-liveness.test.ts

@@ -1,12 +1,12 @@
-/**
- * @system server-boot
- * @status handwritten
- * @edit edit directly
- *
- * Unit tests for the pure `detectLivenessTransitions` core of the
- * `whatsapp-liveness` monitor. The handler's GOWA poll + recordEvent emission is
- * runtime-verified by the scheduled_job firing; this locks the transition logic.
- */
+// ! @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 { expect, test } from "bun:test";
 import { detectLivenessTransitions } from "./whatsapp-liveness-logic.ts";
 

package/src/interpolate-meta.ts

@@ -0,0 +1,123 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Template interpolation against URL params and resolved loader data:
+ * resolveParamRef, interpolateTemplate, and the meta-context filler.
+ *
+ * interpolateTemplate moved here from resolve-from-loader-config.ts
+ * (file-size-budget): interpolation is its own canonical unit and the meta
+ * filler already consumed it, so the import direction now points at the
+ * family home instead of the wave resolver.
+ *
+ * An unresolved ref keeps its literal template rather than becoming
+ * undefined — a page whose brand failed should show a raw `:brand.companyName`
+ * somewhere visible rather than silently dropping its title.
+ */
+
+export 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];
+}
+
+export 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;
+}
+
+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;
+}

package/src/is-react-element-type.test.ts

@@ -1,12 +1,11 @@
-/**
- * @system ui-service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Pins the three React idioms a `typeof === "function"` check silently rejects.
- * The memo case is the measured one: PresenceAvatars rendered blank on every
- * scala-projects page carrying it, because memo() returns an object.
- */
+// ! @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 { expect, test } from "bun:test";
 import { forwardRef, lazy, memo } from "react";

package/src/loader-errors.ts

@@ -0,0 +1,41 @@
+/**
+ * @system ui-service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Error vocabulary for resource_loader source resolution. Split out of
+ * resolve-from-loader-config (file-size-budget): the classes are the
+ * name-matched contract other layers key on, and they belong where they
+ * can be imported without dragging the wave resolver with them.
+ */
+
+export 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";
+	}
+}
+
+/**
+ * A Prisma/pg query rejected an interpolated URL param as not a valid uuid
+ * (pg 22P02 surfaced as the generated client's SqlQueryError). The value came
+ * from the URL, so the URL names no row — the same state as a deleted row,
+ * not a renderer failure. Deliberately a tight name+message match: a
+ * genuinely malformed query is a config fault and must keep failing loudly.
+ *
+ * Measured 2026-09-12 on scala-quiz prod: scanner paths (/.env, /robots.txt,
+ * *.php) and slug links each threw `invalid input syntax for type uuid` as a
+ * 500 after a ~2.5s DB round trip, and the page-server:render-budget breaker
+ * counted them as CONSECUTIVE render failures — 53 in a row on 2026-09-11 —
+ * so the layer sat DEGRADED fail-closed and every real quiz page 503'd for
+ * hours while the only successful render in the window was a crawler.
+ */
+export function isUrlRefNotUuidError(err: unknown): boolean {
+	return (
+		err instanceof Error &&
+		err.name === "SqlQueryError" &&
+		err.message.includes("invalid input syntax for type uuid")
+	);
+}

package/src/module-not-found.test.ts

@@ -1,15 +1,11 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Locks the mount candidate-chain regression (2026-08-24): scala-agents-ui
- * crash-looped at boot because @teamscala/cli-session exports ./boot/mount.ts
- * and not ./mount.ts. The chain already listed boot/mount.ts as a fallback,
- * but Bun names an unexported subpath by its BARE package, so the first
- * candidate's miss was classified as a real error and boot died before the
- * fallback ran. The whole value of the chain is that candidate 1 may be absent.
- */
+// ! @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, it } from "bun:test";
 import { barePackageOf, isModuleNotFound } from "./module-not-found";

package/src/mount-orpc-router.test.ts

@@ -1,12 +1,11 @@
-/**
- * @system service-boot
- * @status handwritten
- * @edit edit directly
- *
- * Regression coverage for the generated-router boot seam. A service schema
- * without its generated router is a codegen failure, not a daemon-only
- * service, so production boot must fail before it can report healthy.
- */
+// ! @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, describe, expect, mock, test } from "bun:test";

package/src/page-server-orpc/server-client.test.ts

@@ -1,20 +1,11 @@
-/**
- * @system page-server
- * @status handwritten
- * @edit edit directly
- *
- * The empty-router substitute that hid a total outage.
- *
- * MEASURED 2026-08-20: scala-quiz and scala-forms served 500s on every
- * data-backed page for hours. /health returned 200 and boot logged "ORPC
- * serverClient registered", because an unregistered read was answered with
- * `createRouterClient({}, …)` — a client that looks registered and carries no
- * models. The fault only surfaced later and elsewhere, as
- * MissingLoaderModelCapabilityError during page render.
- *
- * These pin the contract: a missing client is an error at the point of the
- * fault, never a fabricated stand-in.
- */
+// ! @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 { afterEach, describe, expect, test } from "bun:test";
 import {

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";