@teamscala/service-boot 0.23.355 → 0.23.357

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.355",
+  "version": "0.23.357",
   "sideEffects": false,
   "imports": {
     "#service-boot/*": "./src/*",
@@ -36,7 +36,6 @@
     "@teamscala/object-storage": "*",
     "@teamscala/orpc": "*",
     "@teamscala/os": "*",
-    "@teamscala/proc-walker": "*",
     "@teamscala/realtime-utils": "*",
     "@teamscala/resolver-engine": "*",
     "@teamscala/timing": "*",
@@ -898,22 +897,6 @@
       "types": "./src/security-headers.d.ts",
       "default": "./src/security-headers.ts"
     },
-    "./serve/serve": {
-      "types": "./src/serve/serve.d.ts",
-      "default": "./src/serve/serve.ts"
-    },
-    "./serve/serve.ts": {
-      "types": "./src/serve/serve.d.ts",
-      "default": "./src/serve/serve.ts"
-    },
-    "./serve/stamp-transport-identity": {
-      "types": "./src/serve/stamp-transport-identity.d.ts",
-      "default": "./src/serve/stamp-transport-identity.ts"
-    },
-    "./serve/stamp-transport-identity.ts": {
-      "types": "./src/serve/stamp-transport-identity.d.ts",
-      "default": "./src/serve/stamp-transport-identity.ts"
-    },
     "./server-error-page": {
       "types": "./src/server-error-page.d.ts",
       "default": "./src/server-error-page.ts"

package/src/handlers/lane-attention-sweep.ts

@@ -0,0 +1,81 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `lane-attention-sweep` pg-boss handler. Calls the database function that
+ * reminds an orchestrator about lanes waiting on it, and records the outcome.
+ *
+ * This handler holds NO POLICY. Which lanes are waiting, how long counts as
+ * waiting, who is told, what the message says, and how often it may repeat are
+ * all in `lane_needs_attention` and `sweep_lanes_needing_attention` — so
+ * changing any of them is a migration, not a rebuild and redeploy of this
+ * service. All this file supplies is the tick and the telemetry.
+ *
+ * WHY A TICK EXISTS AT ALL, given `observability-is-passive` and
+ * `no-polling-for-pushable-state`. Both forbid polling for state a source CAN
+ * push. Here the trigger is the PASSAGE OF TIME against a threshold: a lane
+ * going silent emits nothing, because emitting is exactly what it stopped
+ * doing. There is no state transition to react to, so nothing could push it.
+ * The same justification `registry-stale-inactive-sweep` carries, recorded on
+ * the row as `poll_justification`.
+ *
+ * Registered under slug `@teamscala/service-boot:lane-attention-sweep`.
+ */
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+import { getPrisma } from "@teamscala/db/prisma-registry";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+
+interface RemindedLane {
+	task_id: string;
+	window_name: string | null;
+	reason: string;
+	orchestrator_task_id: string;
+}
+
+async function laneAttentionSweep(ctx: { config: ScheduledJobConfig }): Promise<void> {
+	const log = getAppLogger();
+	const prisma = getPrisma();
+
+	// The repeat window is the row's, so silencing a chatty reminder is a
+	// registry edit. The default lives in the SQL function's signature, which is
+	// the one place it is defined.
+	const repeatAfter = (ctx.config as { repeat_after?: string }).repeat_after;
+
+	const reminded = repeatAfter
+		? await prisma.$queryRawUnsafe<RemindedLane[]>(
+				"SELECT * FROM sweep_lanes_needing_attention($1::interval)",
+				repeatAfter,
+			)
+		: await prisma.$queryRawUnsafe<RemindedLane[]>("SELECT * FROM sweep_lanes_needing_attention()");
+
+	// Emitted even when nothing was due. A sweep that only reports on the runs
+	// where it found something is indistinguishable from a sweep that stopped
+	// running, and this exists precisely to notice silence.
+	recordEvent({
+		kind: "fleet.lane-attention.swept",
+		payload: {
+			remindedCount: reminded.length,
+			lanes: reminded.map((lane) => ({
+				task: lane.task_id,
+				window: lane.window_name,
+				reason: lane.reason,
+				toldOrchestrator: lane.orchestrator_task_id,
+			})),
+		},
+	});
+
+	if (reminded.length > 0) {
+		log.info(
+			`[lane-attention-sweep] reminded ${reminded.length} orchestrator(s) about waiting lanes`,
+			{ lanes: reminded.map((lane) => `${lane.window_name}: ${lane.reason}`) },
+		);
+	}
+}
+
+pgBossHandlerRegistry.register(
+	"@teamscala/service-boot:lane-attention-sweep",
+	laneAttentionSweep as (ctx: { config: ScheduledJobConfig }) => Promise<void>,
+);

package/src/pg-boss-mount.ts

@@ -34,6 +34,7 @@ import "./handlers/scala-tools-currency-watch.ts";
 import "./handlers/singleton-tools-currency-watch.ts";
 import "./handlers/registry-stale-inactive-sweep.ts";
 import "./handlers/pane-outbox-drain.ts";
+import "./handlers/lane-attention-sweep.ts";
 
 /**
  * Module-level reference to the mounted PgBoss instance — set by mountPgBoss on

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

@@ -10,7 +10,14 @@
  */
 
 import { describe, expect, test } from "bun:test";
-import { interpolateMeta } from "./resolve-from-loader-config";
+import {
+	interpolateMeta,
+	resolveFromLoaderConfig,
+} from "./resolve-from-loader-config";
+import {
+	getServerClient,
+	setServerClient,
+} from "./page-server-orpc/server-client";
 
 describe("interpolateMeta (resolver_input ref contract)", () => {
 	test("a bare :sourceKey ref passes the whole resolved source object", () => {
@@ -42,3 +49,57 @@ describe("interpolateMeta (resolver_input ref contract)", () => {
 		expect(out.score).toBe(48);
 	});
 });
+
+describe("resource-loader model capability", () => {
+	test("an optional source still refuses a model absent from the generated client", async () => {
+		const original = getServerClient();
+		setServerClient({} as never);
+		try {
+			await expect(
+				resolveFromLoaderConfig(
+					{
+						sources: [
+							{
+								key: "body",
+								source: "orpc",
+								model: "builda_pages",
+								optional: true,
+							},
+						],
+					},
+					{},
+				),
+			).rejects.toThrow(
+				'requires model "builda_pages", but the generated server client does not expose findFirst',
+			);
+		} finally {
+			setServerClient(original);
+		}
+	});
+
+	test("an optional source may resolve an absent row when the model capability exists", async () => {
+		const original = getServerClient();
+		setServerClient({
+			builda_pages: { findFirst: async () => null },
+		} as never);
+		try {
+			await expect(
+				resolveFromLoaderConfig(
+					{
+						sources: [
+							{
+								key: "body",
+								source: "orpc",
+								model: "builda_pages",
+								optional: true,
+							},
+						],
+					},
+					{},
+				),
+			).resolves.toEqual({ body: null });
+		} finally {
+			setServerClient(original);
+		}
+	});
+});

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

@@ -34,6 +34,15 @@ 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>,
@@ -161,7 +170,9 @@ async function resolveSource(
 						}) => Promise<unknown>;
 				  }
 				| undefined;
-			if (!model?.findFirst) return null;
+			if (!model?.findFirst) {
+				throw new MissingLoaderModelCapabilityError(source.model, source.key);
+			}
 			return model.findFirst({
 				where,
 				select: toSelectMap(source.select),
@@ -261,7 +272,10 @@ export async function resolveFromLoaderConfig(
 			if (!source || !result) continue;
 			if (result.status === "fulfilled") {
 				resolved[source.key] = result.value;
-			} else if (source.optional) {
+			} else if (
+				source.optional &&
+				!(result.reason instanceof MissingLoaderModelCapabilityError)
+			) {
 				resolved[source.key] = null;
 			} else {
 				throw result.reason;