@teamscala/service-boot 0.23.421 → 0.23.426

package/src/fn-routers/assessment-report-data.ts

@@ -0,0 +1,423 @@
+/**
+ * @system service-boot
+ * @status handwritten @indivisible-unit owner=lane/idle-pools-hold-the-ceiling reason="one report-shaping unit: band selection, narrative and chart shaping change together"
+ * @edit edit directly
+ *
+ * report-data.ts — quiz-results → report data generation.
+ *
+ * Shapes a stored assessment response into the data the report puck_page
+
+ * renders. The response already carries total_score + category_scores
+ * (computed at submit time), so this is pure shaping — no re-scoring and no
+ * authored copy. The `computeReportData` resolver_fn (a resource_loader
+ * source, key `reportData`) runs this at SSR; the report blocks bind its
+ * fields through the unified page-data surface (`dataSource:"page-data"` +
+ * `fieldPath:"reportData.<key>"`).
+ *
+ * @see scala-docs/curated/apps/messaging.md is unrelated; the stage model
+ * lives on `assessments.stage_bands` (migration 560/561).
+ */
+
+/** A chart data point — structural match for @teamscala/chart-block's ChartPoint. */
+export interface ReportChartPoint {
+	label: string;
+	value: number;
+	color?: string;
+}
+
+/** A derived pillar position for the Positioning card (label + advisory summary). */
+export interface PillarPosition {
+	label: string;
+	summary: string;
+}
+
+/** One roadmap phase — a focus word plus its actions. */
+export interface RoadmapPhase {
+	focus: string;
+	actions: string[];
+}
+
+/**
+ * A list item carrying its own ordinal. The number lives WITH the item so a
+ * fixed-slot layout cannot print a badge for an item that does not exist: a
+ * stage authoring four strengths into six slots leaves slots five and six with
+ * no number and no text, rather than a bare numeral beside empty space. Numbers
+ * spelled in the page instead would be a second copy of the list's length.
+ */
+export interface NumberedItem {
+	index: string;
+	text: string;
+}
+
+/** A titled action with its explanatory line. */
+export interface TitledAction {
+	title: string;
+	description: string;
+}
+
+/**
+ * One stage band, as authored on `assessments.stage_bands`. Every field is
+ * copy the business owns; nothing here is computed. `max` is the inclusive
+ * upper bound of the band — the final band omits it and catches the rest.
+ */
+export interface StageBand {
+	name: string;
+	max?: number;
+	tagline?: string;
+	executiveSummary?: string;
+	strongestAreas?: string[];
+	priorityActions?: TitledAction[];
+	strategicFocus?: string;
+	strengths?: string[];
+	opportunities?: string[];
+	twelveMonthTarget?: string;
+	/**
+	 * The remaining elements of Anna's five-page template. Every one is COPY,
+	 * authored per stage like the rest — none can be derived from the response.
+	 * Wiring them here makes each a row edit rather than a build task: the page
+	 * binds them and hides the section (`visibleWhenPath`) until a stage fills
+	 * it in, so Anna can land them one at a time without a deploy.
+	 */
+	whoYouHelp?: string;
+	knownFor?: string;
+	insights?: string[];
+	contentThemes?: TitledAction[];
+	contentRhythm?: string;
+	northStar?: string;
+	priorityFocus?: string;
+	priorityFocusSummary?: string;
+	recommendedTier?: string;
+	tierSummary?: string;
+	whyItFits?: string;
+	whatItSolves?: string;
+	implementationFocus?: string;
+	expectedOutcome?: string;
+	finalWord?: string;
+	roadmap?: Record<string, RoadmapPhase>;
+	pillarNotes?: Record<string, string>;
+}
+
+/**
+ * One pillar as the report presents it: the authored label and subtitle, this
+ * person's score, the stage's note, and the pillar's colour. Held in the
+ * assessment's own category order (not sorted by score) because the design
+ * shows the three pillars in a fixed sequence with fixed colours.
+ */
+export interface PillarCard {
+	label: string;
+	subtitle: string;
+	value: number;
+	max: number;
+	note: string;
+	color: string;
+}
+
+/** Per-category display authored on `assessments.category_descriptions`. */
+export interface CategoryDisplay {
+	description?: string;
+	subtitle?: string;
+	color?: string;
+	max?: number;
+}
+
+/** The shape a report resource_loader stamps into loaderData for the blocks. */
+export interface ReportData {
+	/** the three pillars in authored order, for the pillar cards */
+	pillarCards: PillarCard[];
+	reportScore: ReportChartPoint[];
+	reportPillars: ReportChartPoint[];
+	narrative: string;
+	totalScore: number;
+	/** overall band label — the Snapshot stage badge */
+	stage: string;
+	/** band advice — the Snapshot stage summary */
+	stageSummary: string;
+	/** highest-scoring pillar — the Positioning "Strongest Pillar" column */
+	strongest: PillarPosition | null;
+	/** mid pillar — the Positioning "Biggest Opportunity" column */
+	opportunity: PillarPosition | null;
+	/** lowest pillar — the Positioning "Authority Gap" column */
+	authorityGap: PillarPosition | null;
+	/** section 4 — what this person already has going for them */
+	strongestAreas: string[];
+	/** section 6 — the numbered actions for this stage */
+	priorityActions: TitledAction[];
+	/** section 7 */
+	strategicFocus: string;
+	/** section 8, left column */
+	strengths: string[];
+	/** section 8, right column */
+	opportunities: string[];
+	/** section 8 left, numbered for badge rendering */
+	strengthsList: NumberedItem[];
+	/** section 8 right, numbered for badge rendering */
+	opportunitiesList: NumberedItem[];
+	/** section 9 */
+	twelveMonthTarget: string;
+	/** section 10 — three phases, each a focus word plus four actions */
+	roadmap: RoadmapPhase[];
+	/** Anna's remaining template elements — empty until a stage authors them. */
+	whoYouHelp: string;
+	knownFor: string;
+	insights: string[];
+	contentThemes: TitledAction[];
+	contentRhythm: string;
+	northStar: string;
+	priorityFocus: string;
+	priorityFocusSummary: string;
+	recommendedTier: string;
+	tierSummary: string;
+	whyItFits: string;
+	whatItSolves: string;
+	implementationFocus: string;
+	expectedOutcome: string;
+	finalWord: string;
+}
+
+/** Minimal view of the stored response — total_score + category_scores. */
+export interface ReportResponseInput {
+	total_score?: number | null;
+	category_scores?: Record<string, number> | null;
+}
+
+/** Minimal view of the assessment metadata — title plus the stage model. */
+export interface ReportAssessmentInput {
+	title?: string | null;
+	stage_bands?: unknown;
+	/** authored pillar order, e.g. ["Be Seen", "Be Heard", "Be Chosen"] */
+	categories?: unknown;
+	/** per-pillar display: subtitle, colour, description */
+	category_descriptions?: unknown;
+}
+
+/** The fallback pillar colour when the assessment authors none. */
+const DEFAULT_PILLAR_COLOR = "var(--color-primary)";
+
+/**
+ * Match a pillar label to its authored stage note.
+ *
+ * The stage designs key these notes by the distinctive word — `seen`, `heard`,
+ * `chosen` — while the assessment names the pillars "Be Seen", "Be Heard",
+ * "Be Chosen". A plain lowercase lookup therefore missed EVERY note, and the
+ * positioning cards silently fell back to their generic role lines: present,
+ * plausible, and identical for every respondent, so nothing looked broken.
+
+ * Tries the whole label first, then the last word, so either authoring style
+ * resolves and neither has to know about the other.
+ */
+export function pillarNote(band: StageBand | null, label: string): string {
+	const notes = band?.pillarNotes;
+	if (!notes) return "";
+	const whole = label.trim().toLowerCase();
+	const lastWord = whole.split(/\s+/).pop() ?? whole;
+	return (notes[whole] ?? notes[lastWord] ?? "").trim();
+}
+
+/**
+ * Build the pillar cards in the assessment's OWN category order. Sorting by
+ * score is right for "strongest / gap" positioning and wrong here: a reader
+ * comparing two reports needs the pillars in the same place every time, and
+ * each pillar keeps one colour across every report.
+ */
+export function buildPillarCards(
+	assessment: ReportAssessmentInput | null | undefined,
+	categoryScores: Record<string, number>,
+	band: StageBand | null,
+): PillarCard[] {
+	const categories = Array.isArray(assessment?.categories)
+		? (assessment.categories as unknown[]).filter(
+				(c): c is string => typeof c === "string" && c.length > 0,
+			)
+		: Object.keys(categoryScores);
+	const display = (
+		assessment?.category_descriptions && typeof assessment.category_descriptions === "object"
+			? assessment.category_descriptions
+			: {}
+	) as Record<string, CategoryDisplay | string>;
+	return categories.map((label) => {
+		const raw = display[label];
+		const cfg: CategoryDisplay = typeof raw === "string" ? { description: raw } : (raw ?? {});
+		const score = Number(categoryScores[label] ?? 0);
+		return {
+			label,
+			subtitle: cfg.subtitle ?? "",
+			value: Number.isFinite(score) ? Math.max(0, Math.round(score)) : 0,
+			max: typeof cfg.max === "number" && cfg.max > 0 ? cfg.max : 100,
+			note: pillarNote(band, label) || cfg.description || "",
+			color: cfg.color || DEFAULT_PILLAR_COLOR,
+		};
+	});
+}
+
+/**
+ * Read the authored bands off the assessment row. Returns [] when the column
+ * is null or malformed, which is the signal to fall back rather than throw —
+ * a report that renders a score with no stage copy is degraded; one that 500s
+ * because a JSON column is empty is broken.
+ */
+export function readStageBands(assessment?: ReportAssessmentInput | null): StageBand[] {
+	const raw = assessment?.stage_bands;
+	if (!raw || typeof raw !== "object") return [];
+	const bands = (raw as { bands?: unknown }).bands;
+	if (!Array.isArray(bands)) return [];
+	return bands.filter(
+		(band): band is StageBand =>
+			!!band && typeof band === "object" && typeof (band as StageBand).name === "string",
+	);
+}
+
+/**
+ * Select the band a score falls in. Bands are ascending by `max`; the first
+ * whose `max` the score does not exceed wins, and a band without `max` is the
+ * catch-all. Authored order is respected rather than re-sorted, so a
+ * mis-ordered row is visible in the output instead of silently corrected.
+ */
+export function selectStageBand(bands: StageBand[], score: number): StageBand | null {
+	for (const band of bands) {
+		if (typeof band.max !== "number") return band;
+		if (score <= band.max) return band;
+	}
+	return bands.length > 0 ? (bands[bands.length - 1] ?? null) : null;
+}
+
+/**
+ * The narrative is authored per band and carries `{{score}}` where the design
+ * spelled a number, so one band serves every score inside it. With no band,
+ * the fallback states the score and nothing it cannot support.
+ */
+export function generateNarrative(
+	totalScore: number,
+	band: StageBand | null,
+	assessment?: ReportAssessmentInput | null,
+): string {
+	const authored = band?.executiveSummary?.trim();
+	if (authored) return authored.replaceAll("{{score}}", String(totalScore));
+	const title = assessment?.title?.trim() || "your assessment";
+	return `You scored ${totalScore} on ${title}.`;
+}
+
+/** Pair each item with its 1-based ordinal for badge rendering. */
+export function numberItems(items: string[] | undefined): NumberedItem[] {
+	if (!Array.isArray(items)) return [];
+	return items
+		.filter((text): text is string => typeof text === "string" && text.trim().length > 0)
+		.map((text, i) => ({ index: String(i + 1), text: text.trim() }));
+}
+
+/** Flatten the authored `{month1, month2, month3}` map into render order. */
+export function orderRoadmap(roadmap: Record<string, RoadmapPhase> | undefined): RoadmapPhase[] {
+	if (!roadmap || typeof roadmap !== "object") return [];
+	return Object.keys(roadmap)
+		.sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
+		.map((key) => roadmap[key])
+		.filter((phase): phase is RoadmapPhase => !!phase && Array.isArray(phase.actions));
+}
+
+/**
+ * Resolver call shape: the resolver_fn executor invokes every resolver as
+ * `fn({ input, client, params })` (see resolveByResolverFn in
+ * @teamscala/service-boot/resolve-from-loader-config). computeReportData is
+ * registered as the `computeReportData` resolver_fn row, so it receives that
+ * context — input.response / input.assessment come from the loader's
+ * resolver_input ({response: ':response', assessment: ':assessment'}).
+ */
+export function computeReportData({
+	input,
+}: {
+	input: {
+		response?: ReportResponseInput | null;
+		assessment?: ReportAssessmentInput | null;
+	};
+}): ReportData {
+	const { response, assessment } = input;
+	const totalScore = Math.max(0, Math.round(Number(response?.total_score ?? 0)));
+	const categoryScores = response?.category_scores ?? {};
+	const reportScore: ReportChartPoint[] = [{ label: "Score", value: totalScore }];
+	const reportPillars: ReportChartPoint[] = Object.entries(categoryScores)
+		.filter(([, value]) => Number.isFinite(Number(value)))
+		.map(([label, value]) => ({ label, value: Math.max(0, Math.round(Number(value))) }))
+		.filter((p) => p.label.length > 0)
+		.sort((a, b) => b.value - a.value);
+
+	const band = selectStageBand(readStageBands(assessment), totalScore);
+	const narrative = generateNarrative(totalScore, band, assessment);
+	const pillarCards = buildPillarCards(assessment, categoryScores, band);
+	// The chart bars take each pillar's own colour, so the bar chart and the
+	// pillar cards cannot disagree about which colour means which pillar.
+	// Only an AUTHORED colour travels to the chart. When the assessment sets
+	// none, the bars keep the chart's own default rather than being stamped with
+	// the cards' fallback — an assessment that never asked for pillar colours
+	// gets exactly the output it got before.
+	const colorFor = new Map(
+		pillarCards.filter((c) => c.color !== DEFAULT_PILLAR_COLOR).map((c) => [c.label, c.color]),
+	);
+	for (const point of reportPillars) {
+		const color = colorFor.get(point.label);
+		if (color) point.color = color;
+	}
+
+	// The positioning trio names the pillar; the advisory line beside it is the
+	// band's note for that pillar when one is authored, otherwise the generic
+	// role of that column. Falling back per-column rather than dropping the
+	// whole card keeps the section rendering while copy is still being written.
+	const noteFor = (label: string, fallback: string): string =>
+		pillarNote(band, label) || fallback;
+	const pos = (p: ReportChartPoint | undefined, fallback: string): PillarPosition | null =>
+		p ? { label: p.label, summary: noteFor(p.label, fallback) } : null;
+
+	const strongest = pos(
+		reportPillars[0],
+		"Your strongest pillar — protect and compound this advantage.",
+	);
+	const opportunity =
+		reportPillars.length >= 3
+			? pos(
+					reportPillars[1],
+					"Your biggest growth opportunity — focused effort here lifts overall authority.",
+				)
+			: null;
+	const authorityGap =
+		reportPillars.length >= 2
+			? pos(
+					reportPillars[reportPillars.length - 1],
+					"Your lowest pillar — the single biggest lever for improvement right now.",
+				)
+			: null;
+
+	return {
+		pillarCards,
+		reportScore,
+		reportPillars,
+		narrative,
+		totalScore,
+		stage: band?.name ?? "",
+		stageSummary: band?.tagline ?? "",
+		strongest,
+		opportunity,
+		authorityGap,
+		strongestAreas: band?.strongestAreas ?? [],
+		priorityActions: band?.priorityActions ?? [],
+		strategicFocus: band?.strategicFocus ?? "",
+		strengths: band?.strengths ?? [],
+		opportunities: band?.opportunities ?? [],
+		strengthsList: numberItems(band?.strengths),
+		opportunitiesList: numberItems(band?.opportunities),
+		twelveMonthTarget: band?.twelveMonthTarget ?? "",
+		roadmap: orderRoadmap(band?.roadmap),
+		whoYouHelp: band?.whoYouHelp ?? "",
+		knownFor: band?.knownFor ?? "",
+		insights: band?.insights ?? [],
+		contentThemes: band?.contentThemes ?? [],
+		contentRhythm: band?.contentRhythm ?? "",
+		northStar: band?.northStar ?? "",
+		priorityFocus: band?.priorityFocus ?? "",
+		priorityFocusSummary: band?.priorityFocusSummary ?? "",
+		recommendedTier: band?.recommendedTier ?? "",
+		tierSummary: band?.tierSummary ?? "",
+		whyItFits: band?.whyItFits ?? "",
+		whatItSolves: band?.whatItSolves ?? "",
+		implementationFocus: band?.implementationFocus ?? "",
+		expectedOutcome: band?.expectedOutcome ?? "",
+		finalWord: band?.finalWord ?? "",
+	};
+}

package/src/fn-routers/assessment-report-email.ts

@@ -20,11 +20,11 @@ import { resolveEmailSender } from "@teamscala/email/identity/resolve-email-send
 import { decryptSecretConfig } from "@teamscala/encryption/crypto/secret-config";
 import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
 import { fetchOrgBrand } from "@teamscala/resolver-engine/data-resolvers/fetch-org-brand";
-import type { StageBand } from "@teamscala/assessment-block/report-data";
+import type { StageBand } from "./assessment-report-data.ts";
 import {
 	generateNarrative,
 	orderRoadmap,
-} from "@teamscala/assessment-block/report-data";
+} from "./assessment-report-data.ts";
 
 export async function sendAuthorityReportEmail(opts: {
 	to: string;

package/src/fn-routers/chat-session-router-shared.ts

@@ -4,11 +4,11 @@
  * @edit edit directly
  *
  * The valibot schemas + row helpers of the chatSession ORPC router: procedure
- * input schemas, the conversation ownership check, and the stored-row → wire
- * message mapping.
+ * input schemas, and the stored-row → wire message mapping.
  *
  * Split out of fn-routers/chat-session-router.ts (455 lines) — byte-for-byte
- * move; import paths adjusted only.
+ * move; import paths adjusted only. Conversation ownership lives in its own
+ * sibling, ./conversation-ownership.ts (single-canonical-unit).
  */
 
 import * as v from "valibot";
@@ -90,25 +90,8 @@ export async function throwForbidden(message: string): Promise<never> {
 	throw new ORPCError("FORBIDDEN", { message });
 }
 
-/**
- * Reject if the conversation does not belong to the calling user. Ownership
- * by user_id is the complete proof (the row was created with this user's id);
- * no org check needed.
- */
-export async function assertOwns(
-	prisma: any,
-	conversationId: string,
-	user: SessionUser,
-): Promise<any> {
-	const conv = await prisma.conversations.findUnique({
-		where: { id: conversationId },
-	});
-	if (!conv || conv.user_id !== user.id) await throwForbidden("Conversation not found.");
-	return conv;
-}
-
 /** Map stored message rows to the wire shape the chat client restores. */
-export function mapMessages(msgs: any[]) {
+export function mapMessages(msgs: unknown[]) {
 	return msgs
 		.filter((m: any) => m.role === "user" || m.role === "assistant")
 		.map((m: any) => ({

package/src/fn-routers/chat-session-router.ts

@@ -37,7 +37,6 @@ import { authed, type Context } from "./auth-router.ts";
 import { persistChatMessages } from "./persist-chat-messages.ts";
 
 import {
-	assertOwns,
 	assistantType,
 	clearSchema,
 	createOrRestoreSchema,
@@ -50,6 +49,7 @@ import {
 	SessionUser,
 	throwForbidden,
 } from "./chat-session-router-shared.ts";
+import { assertOwns } from "./conversation-ownership.ts";
 
 export const chatSessionRouter = {
 	// createOrRestore — resume the caller's most-recent ACTIVE thread for this

package/src/fn-routers/conversation-ownership.ts

@@ -0,0 +1,23 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Conversation ownership assertion for the chatSession ORPC router — the
+ * reject-if-not-yours gate every mutating procedure runs before touching rows.
+ */
+
+import { throwForbidden, type SessionUser } from "./chat-session-router-shared.ts";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export async function assertOwns(
+	prisma: any,
+	conversationId: string,
+	user: SessionUser,
+): Promise<unknown> {
+	const conv = await prisma.conversations.findUnique({
+		where: { id: conversationId },
+	});
+	if (!conv || conv.user_id !== user.id) await throwForbidden("Conversation not found.");
+	return conv;
+}

package/src/fn-routers/index.ts

@@ -16,7 +16,7 @@
  */
 
 import { registerCustomRouter } from "@teamscala/orpc/app-router";
-import { puckPagesRouter } from "@teamscala/service-boot/page-server-orpc/puck-pages-router";
+import { puckPagesRouter } from "../page-server-orpc/puck-pages-router";
 import { watchDataChange } from "@teamscala/realtime-utils/data-change-procedure";
 import { watchPresence } from "@teamscala/realtime-utils/presence-procedure";
 import { agreementSendRouter } from "./agreement-send-router.ts";

package/src/fn-routers/public-agreement-router.ts

@@ -49,7 +49,7 @@ export type { CertificateData, CertificateCopy } from "./agreement-certificate.t
 interface Context {
 	prisma: any;
 	headers: Headers;
-	resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<unknown>;
 }
 
 const pub = os.$context<Context>();

package/src/fn-routers/public-assessment-router.ts

@@ -22,14 +22,14 @@ import { recordEvent } from "@teamscala/event-log/record-event";
 import {
 	readStageBands,
 	selectStageBand,
-} from "@teamscala/assessment-block/report-data";
+} from "./assessment-report-data.ts";
 import { sendAuthorityReportEmail } from "./assessment-report-email.ts";
 import { scoreAnswers, toBandSlug, type StoredQuestion } from "./assessment-scoring.ts";
 
 interface Context {
 	prisma: any;
 	headers: Headers;
-	resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<unknown>;
 }
 
 const pub = os.$context<Context>();

package/src/fn-routers/public-gpt-session-router.ts

@@ -17,7 +17,7 @@ import { persistChatMessages } from "./persist-chat-messages.ts";
 interface Context {
 	prisma: any;
 	headers: Headers;
-	resolveUser?: (headers: Headers, prisma: any) => Promise<any>;
+	resolveUser?: (headers: Headers, prisma: any) => Promise<unknown>;
 }
 
 const pub = os.$context<Context>();

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

@@ -33,6 +33,22 @@ export const FaultEscalationConfigSchema = v.object({
 		),
 	),
 	resolve_after_minutes: v.number(),
+	/** Per-kind volume sources closing the quiet-vs-dead gap: a fault kind
+	 * whose producer can DIE maps to the kind whose row VOLUME proves the
+	 * pipeline alive. Without a source, resolution on quiet is unchanged;
+	 * with one, resolve additionally requires the volume floor in-window,
+	 * and quiet-with-zero-volume HOLDS the episode open instead (one hold
+	 * notice per episode-state — measured 2026-08-27: the dead llm-router
+	 * emitted zero failures and the sweep closed as healthy). */
+	volume_sources: v.optional(
+		v.record(
+			v.string(),
+			v.object({
+				volume_kind_pattern: v.string(),
+				min_volume: v.optional(v.number()),
+			}),
+		),
+	),
 	/** The orchestrator's work item — escalations are COMMENTS on it, never
 	 * task rows (the fleet-task-placement CHECK constraint refuses a system
 	 * task without session identity, and an escalation is a finding, not an