@teamscala/service-boot 0.23.284

package/src/handlers/upstream-issue-sync.ts

@@ -0,0 +1,210 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `upstream-issue-sync` pg-boss handler (doctrine `upstream-issues-tracked-in-
+ * registry`). For each active `upstream_issue` registry row it polls the row's
+ * GitHub issue + comments and writes back `state` / `comment_count` /
+ * `last_comment_at` / `latest_response` / `last_synced_at`, emitting
+ * `recordEvent({ kind: "upstream.issue.response" })` when a NEW maintainer
+ * (non-filer) comment appears — so a maintainer response on an issue we filed
+ * never goes unnoticed.
+ *
+ * Polls via the authenticated `gh` CLI (`@teamscala/os` spawn — `gh api` is the
+ * off-the-shelf GitHub client; NOT a bespoke fetch). The intended
+ * `@teamscala/api-github` `rest_client` adapter is deferred on the codegen-harness
+ * breakage (open migration `rest-client-codegen-typescript-7-broken`); this
+ * handler migrates to it once the harness is fixed.
+ *
+ * Registered under slug `@teamscala/service-boot:upstream-issue-sync`. Mirrors
+ * `bun-stable-watch` (dev-host pg-boss handler). Reads rows via the `getAllEntries`
+ * helper and writes back via `persistRegistryEntryConfig` (the validated
+ * registry_entries writer — `registry-via-helper` blocks direct registry Prisma
+ * in package code).
+ */
+import { getAllEntries } from "@teamscala/db/registry/accessors";
+import { persistRegistryEntryConfig } from "@teamscala/db/registry/persist-entry-config";
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { spawn } from "@teamscala/os/spawn";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+
+interface GhIssue {
+	state: string;
+	comments: number;
+	author: string;
+}
+
+interface GhComment {
+	author: string;
+	at: string;
+	body: string;
+}
+
+interface CapturedResponse {
+	author: string;
+	excerpt: string;
+	at: string;
+}
+
+const DEFAULT_GH_TIMEOUT_MS = 20_000;
+let cachedGhTimeoutMs: number | undefined;
+async function getGhTimeoutMs(): Promise<number> {
+	if (cachedGhTimeoutMs !== undefined) return cachedGhTimeoutMs;
+	const row = await loadRegistryConfig("config", "upstream-issue-sync", v.looseObject({}));
+	cachedGhTimeoutMs = (row?.gh_timeout_ms as number | undefined) ?? DEFAULT_GH_TIMEOUT_MS;
+	return cachedGhTimeoutMs;
+}
+const EXCERPT_MAX = 160;
+
+/** Fetch a GitHub issue's state/comment-count/author via `gh api`. */
+async function ghIssue(owner: string, repo: string, number: number): Promise<GhIssue | null> {
+	const { stdout, exitCode, stderr } = await spawn({
+		name: "upstream-issue-sync:gh-issue",
+		command: [
+			"gh",
+			"api",
+			`repos/${owner}/${repo}/issues/${number}`,
+			"--jq",
+			"{state: .state, comments: .comments, author: .user.login}",
+		],
+		timeoutMs: await getGhTimeoutMs(),
+	});
+	if (exitCode !== 0) {
+		getAppLogger().warn(
+			`[upstream-issue-sync] gh api issue ${owner}/${repo}#${number} failed: ${stderr.trim() || stdout.trim()}`,
+		);
+		return null;
+	}
+	try {
+		return JSON.parse(stdout) as GhIssue;
+	} catch {
+		return null;
+	}
+}
+
+/** Fetch a GitHub issue's comments via `gh api` (per_page=100). */
+async function ghComments(owner: string, repo: string, number: number): Promise<GhComment[]> {
+	const { stdout, exitCode } = await spawn({
+		name: "upstream-issue-sync:gh-comments",
+		command: [
+			"gh",
+			"api",
+			`repos/${owner}/${repo}/issues/${number}/comments?per_page=100`,
+			"--jq",
+			"[.[] | {author: .user.login, at: .created_at, body: .body}]",
+		],
+		timeoutMs: await getGhTimeoutMs(),
+	});
+	if (exitCode !== 0) return [];
+	try {
+		const parsed = JSON.parse(stdout) as GhComment[];
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+
+function excerpt(body: string): string {
+	const flat = body.replace(/\s+/g, " ").trim();
+	return flat.length > EXCERPT_MAX ? `${flat.slice(0, EXCERPT_MAX)}…` : flat;
+}
+
+/**
+ * The newest comment NOT by the issue filer (a maintainer response), or null.
+ * GitHub returns comments oldest-first; sort by `at` to be safe.
+ */
+function newestMaintainerResponse(
+	comments: GhComment[],
+	filer: string,
+): CapturedResponse | null {
+	const external = comments
+		.filter((c) => c.author !== filer)
+		.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
+	const newest = external[0];
+	if (!newest) return null;
+	return { author: newest.author, excerpt: excerpt(newest.body), at: newest.at };
+}
+
+async function upstreamIssueSync(_ctx: { config: ScheduledJobConfig }): Promise<void> {
+	const log = getAppLogger();
+
+	const rows = getAllEntries().filter(
+		(e) => (e.type as string) === "upstream_issue" && e.is_active,
+	);
+	if (rows.length === 0) {
+		log.info("[upstream-issue-sync] no active upstream_issue rows");
+		return;
+	}
+
+	let updated = 0;
+	for (const row of rows) {
+		const cfg = row.config as Record<string, unknown>;
+		const repo = String(cfg.repo ?? "");
+		const issueNumber = Number(cfg.issue_number);
+		const [owner, repoName] = repo.split("/");
+		if (!owner || !repoName || !Number.isInteger(issueNumber)) {
+			log.warn(`[upstream-issue-sync] row ${row.slug} has invalid repo/issue_number`);
+			continue;
+		}
+
+		const issue = await ghIssue(owner, repoName, issueNumber);
+		if (!issue) continue; // gh failure already logged; skip this row this cycle
+		const comments = await ghComments(owner, repoName, issueNumber);
+		const lastCommentAt =
+			comments.length > 0 ? (comments.map((c) => c.at).sort().at(-1) ?? null) : null;
+		const latestResponse = newestMaintainerResponse(comments, issue.author);
+
+		const prevResponseAt = (
+			cfg.latest_response as { at?: string } | null | undefined
+		)?.at ?? null;
+
+		const nowIso = new Date().toISOString();
+		const nextConfig = {
+			...cfg,
+			state: issue.state === "closed" ? "closed" : "open",
+			comment_count: issue.comments,
+			last_comment_at: lastCommentAt,
+			latest_response: latestResponse,
+			last_synced_at: nowIso,
+		};
+
+		try {
+			await persistRegistryEntryConfig("upstream_issue", row.slug, nextConfig);
+		} catch (err) {
+			log.warn(
+				`[upstream-issue-sync] row ${row.slug} write failed (validation or db): ${err instanceof Error ? err.message : String(err)}`,
+			);
+			continue;
+		}
+		updated += 1;
+
+		// New maintainer response? (newer than the previously-recorded one)
+		const isNewResponse =
+			latestResponse !== null && (prevResponseAt === null || latestResponse.at > prevResponseAt);
+		if (isNewResponse) {
+			recordEvent({
+				kind: "upstream.issue.response",
+				payload: {
+					slug: row.slug,
+					repo,
+					issue_number: issueNumber,
+					author: latestResponse.author,
+					excerpt: latestResponse.excerpt,
+					at: latestResponse.at,
+				},
+			});
+			log.info(
+				`[upstream-issue-sync] ${row.slug}: new maintainer response from @${latestResponse.author}`,
+			);
+		}
+	}
+
+	log.info(`[upstream-issue-sync] synced ${updated}/${rows.length} upstream_issue rows`);
+}
+
+pgBossHandlerRegistry.register("@teamscala/service-boot:upstream-issue-sync", upstreamIssueSync);

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

@@ -0,0 +1,59 @@
+/**
+ * @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.
+ */
+import { beforeEach, expect, mock, test } from "bun:test";
+
+const recordEventCalls: Array<{ kind: string; payload: Record<string, unknown> }> = [];
+
+// The live device list the mocked /mcp forwarder returns — mutated per test.
+let mockDevices: { results: Array<{ id: string; state?: string; jid?: string }> };
+
+mock.module("@teamscala/event-log/record-event", () => ({
+	recordEvent: (e: { kind: string; payload: Record<string, unknown> }) => {
+		recordEventCalls.push(e);
+	},
+}));
+mock.module("@teamscala/chat-completion/central-tool-forwarder", () => ({
+	forwardToolToCentralMcp: async () => mockDevices,
+}));
+
+const { pollWhatsAppLiveness } = await import("./whatsapp-liveness.ts");
+
+beforeEach(() => {
+	recordEventCalls.length = 0;
+});
+
+test("connected → disconnected emits a device.disconnected recordEvent", async () => {
+	// Poll 1: device healthy — seeds the baseline, no event.
+	mockDevices = { results: [{ id: "scala-community", state: "logged_in", jid: "447@s.whatsapp.net" }] };
+	await pollWhatsAppLiveness({ config: {} as never });
+	expect(recordEventCalls, "no event while connected").toEqual([]);
+
+	// Poll 2: device dropped — transition fires the alert.
+	mockDevices = { results: [{ id: "scala-community", state: "logged_out", jid: "447@s.whatsapp.net" }] };
+	await pollWhatsAppLiveness({ config: {} as never });
+
+	expect(recordEventCalls).toHaveLength(1);
+	expect(recordEventCalls[0]!.kind).toBe("messaging.whatsapp.device.disconnected");
+	expect(recordEventCalls[0]!.payload).toMatchObject({
+		device_id: "scala-community",
+		state: "logged_out",
+		jid: "447@s.whatsapp.net",
+	});
+});
+
+test("staying connected across polls emits nothing", async () => {
+	mockDevices = { results: [{ id: "stable-dev", state: "logged_in" }] };
+	await pollWhatsAppLiveness({ config: {} as never });
+	await pollWhatsAppLiveness({ config: {} as never });
+	expect(recordEventCalls).toEqual([]);
+});

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

@@ -0,0 +1,53 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * Pure transition-detection logic for the WhatsApp linked-device liveness monitor
+ * (`whatsapp-liveness` handler). Split out from the GOWA-coupled handler so the
+ * logic is unit-testable with zero adapter dependencies, and the handler is a thin
+ * poll→detect→emit shell. The connection signal is the GOWA device `state` field
+ * (`"logged_in"` == connected) — see `whatsapp-remote-logout-monitor`.
+ */
+
+/** GOWA device `state` value meaning the linked phone is connected + authenticated. */
+export const GOWA_CONNECTED_STATE = "logged_in";
+
+export interface WhatsAppDeviceState {
+	id: string;
+	state: string;
+	jid?: string;
+	display_name?: string;
+}
+
+export interface LivenessTransitions {
+	disconnected: WhatsAppDeviceState[];
+	reconnected: WhatsAppDeviceState[];
+}
+
+/**
+ * Detect connected↔disconnected transitions between the last-known and the freshly
+ * observed device states.
+ *
+ * `prev` is the last-known `state` per device id. A device ABSENT from `prev` is a
+ * first sighting: it seeds the baseline and yields NO transition (so the monitor
+ * never alerts on a state it never observed the device leave, and a process restart
+ * re-baselines without false positives). A device present in `prev` is compared:
+ * connected→not is `disconnected`; not→connected is `reconnected`.
+ */
+export function detectLivenessTransitions(
+	prev: Map<string, string>,
+	curr: WhatsAppDeviceState[],
+): LivenessTransitions {
+	const disconnected: WhatsAppDeviceState[] = [];
+	const reconnected: WhatsAppDeviceState[] = [];
+	for (const dev of curr) {
+		const prevState = prev.get(dev.id);
+		if (prevState === undefined) continue; // first sighting — baseline, no alert
+		const wasConnected = prevState === GOWA_CONNECTED_STATE;
+		const nowConnected = dev.state === GOWA_CONNECTED_STATE;
+		if (wasConnected && !nowConnected) disconnected.push(dev);
+		else if (!wasConnected && nowConnected) reconnected.push(dev);
+	}
+	return { disconnected, reconnected };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * @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.
+ */
+import { expect, test } from "bun:test";
+import { detectLivenessTransitions } from "./whatsapp-liveness-logic.ts";
+
+const dev = (id: string, state: string) => ({ id, state });
+
+test("first sighting of a device is baseline — no transition", () => {
+	const prev = new Map<string, string>(); // never seen
+	const curr = [dev("scala-community", "logged_in"), dev("new-number", "logged_in")];
+	expect(detectLivenessTransitions(prev, curr)).toEqual({
+		disconnected: [],
+		reconnected: [],
+	});
+});
+
+test("connected → disconnected transition is detected", () => {
+	const prev = new Map([["scala-community", "logged_in"]]);
+	const curr = [dev("scala-community", "logged_out")];
+	const out = detectLivenessTransitions(prev, curr);
+	expect(out.disconnected).toHaveLength(1);
+	expect(out.disconnected[0]!.id).toBe("scala-community");
+	expect(out.reconnected).toEqual([]);
+});
+
+test("any non-logged_in state counts as disconnected", () => {
+	const prev = new Map([["d", "logged_in"]]);
+	for (const state of ["logged_out", "connecting", "qr_required", "unknown", ""]) {
+		const out = detectLivenessTransitions(prev, [dev("d", state)]);
+		expect(out.disconnected, `state=${state}`).toHaveLength(1);
+	}
+});
+
+test("disconnected → connected recovery is detected", () => {
+	const prev = new Map([["d", "logged_out"]]);
+	const curr = [dev("d", "logged_in")];
+	const out = detectLivenessTransitions(prev, curr);
+	expect(out.reconnected).toHaveLength(1);
+	expect(out.disconnected).toEqual([]);
+});
+
+test("unchanged state yields no transition", () => {
+	const prev = new Map([
+		["a", "logged_in"],
+		["b", "logged_out"],
+	]);
+	const curr = [dev("a", "logged_in"), dev("b", "logged_out")];
+	expect(detectLivenessTransitions(prev, curr)).toEqual({
+		disconnected: [],
+		reconnected: [],
+	});
+});
+
+test("mixed: one disconnects, one recovers, one baselines, one stable", () => {
+	const prev = new Map<string, string>([
+		["keep-connected", "logged_in"],
+		["will-drop", "logged_in"],
+		["will-recover", "logged_out"],
+		["stays-down", "logged_out"],
+	]);
+	const curr = [
+		dev("keep-connected", "logged_in"),
+		dev("will-drop", "logged_out"),
+		dev("will-recover", "logged_in"),
+		dev("stays-down", "logged_out"),
+		dev("brand-new", "logged_in"), // first sighting — baseline, ignored
+	];
+	const out = detectLivenessTransitions(prev, curr);
+	expect(out.disconnected.map((d) => d.id)).toEqual(["will-drop"]);
+	expect(out.reconnected.map((d) => d.id)).toEqual(["will-recover"]);
+});

package/src/handlers/whatsapp-liveness.ts

@@ -0,0 +1,125 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The `whatsapp-liveness` pg-boss handler — polls GOWA `listDevices` and emits a
+ * `messaging.whatsapp.device.disconnected` recordEvent + operator alert when a
+ * WhatsApp linked device's `state` transitions away from `logged_in`. A phone-side
+ * remote-logout (REMOTE_LOGOUT) emits NO GOWA webhook (its webhook set is
+ * message/ack/group only), so the platform would otherwise only discover the loss
+ * when a tool next needs the device (incident 2026-07-02: ~12h silent drop). This
+ * monitor closes that gap with a ~5min poll (`whatsapp-remote-logout-monitor`).
+ *
+ * The device list is fetched by DISPATCHING the `api_gowa_devices.listDevices` tool
+ * through the central `/mcp` loopback (`forwardToolToCentralMcp`) — reusing the
+ * gateway's single sealed GOWA-credential resolution surface (no cred duplication,
+ * no second resolver, no new process.env injection). The handler carries no GOWA
+ * secrets; it authenticates to its own /mcp with `MCP_CHAT_LOOPBACK_TOKEN` as the
+ * system caller (`MCP_SYSTEM_USER_ID`/`MCP_SYSTEM_ORG_ID` — a platform system
+ * action, not a user-scoped one). The connection signal is the device `state` field
+ * (`"logged_in"` == connected); the pure transition detector + its 8 tests live in
+ * the dependency-free sibling `whatsapp-liveness-logic.ts`. State is held in-process
+ * (Map<deviceId,state>); a process restart re-baselines every device.
+ *
+ * Registered under `@teamscala/service-boot:whatsapp-liveness`.
+ */
+import type { ExecutionContext } from "@teamscala/os/contracts/mcp";
+import type { ScheduledJobConfig } from "@teamscala/db-validation/registry-schemas/scheduled-job";
+import { recordEvent } from "@teamscala/event-log/record-event";
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { pgBossHandlerRegistry } from "../pg-boss-handler-registry.ts";
+import { detectLivenessTransitions, type WhatsAppDeviceState } from "./whatsapp-liveness-logic.ts";
+import { loadRegistryConfig } from "@teamscala/db/registry/load-config";
+import * as v from "valibot";
+
+/** In-process last-known device state, keyed by GOWA device id. */
+const lastKnown = new Map<string, string>();
+
+/** The subset of GOWA's `/devices` response this monitor reads. */
+interface GowaListDevicesResponse {
+	results?: Array<{
+		id: string;
+		state?: string;
+		jid?: string;
+		display_name?: string;
+	}>;
+}
+
+let cachedSystemIdentity: { userId: string | undefined; organisationId: string | undefined } | undefined;
+async function getSystemIdentity(): Promise<{ userId: string | undefined; organisationId: string | undefined }> {
+	if (cachedSystemIdentity) return cachedSystemIdentity;
+	const row = await loadRegistryConfig("config", "system-identity", v.looseObject({}));
+	cachedSystemIdentity = {
+		userId: row?.system_user_id as string | undefined,
+		organisationId: row?.system_org_id as string | undefined,
+	};
+	return cachedSystemIdentity;
+}
+
+export async function pollWhatsAppLiveness({
+	config: _config,
+}: {
+	config: ScheduledJobConfig;
+}): Promise<void> {
+	const log = getAppLogger();
+
+	// System-caller identity (platform action, not user-scoped) — matches the
+	// gateway's system caller; the /mcp resolves it to cross-org super-admin.
+	const { userId, organisationId } = await getSystemIdentity();
+	const systemCtx: ExecutionContext = { userId, organisationId } as ExecutionContext;
+
+	let devices: WhatsAppDeviceState[];
+	try {
+		const { forwardToolToCentralMcp } = await import("@teamscala/chat-completion/central-tool-forwarder");
+		const res = (await forwardToolToCentralMcp(
+			"api_gowa_devices",
+			{ action: "listDevices" },
+			systemCtx,
+		)) as GowaListDevicesResponse | undefined;
+		devices = (res?.results ?? []).map((d) => ({
+			id: d.id,
+			state: d.state ?? "unknown",
+			jid: d.jid,
+			display_name: d.display_name,
+		}));
+	} catch (err) {
+		log.warn(
+			`[whatsapp-liveness] GOWA listDevices via /mcp failed: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		return;
+	}
+
+	const { disconnected, reconnected } = detectLivenessTransitions(lastKnown, devices);
+
+	for (const dev of disconnected) {
+		recordEvent({
+			kind: "messaging.whatsapp.device.disconnected",
+			payload: {
+				device_id: dev.id,
+				jid: dev.jid,
+				display_name: dev.display_name,
+				state: dev.state,
+			},
+		});
+		log.warn(
+			`[whatsapp-liveness] device "${dev.id}" (${dev.jid ?? "?"}) DISCONNECTED (state=${dev.state}) — operator alert emitted`,
+		);
+	}
+	for (const dev of reconnected) {
+		recordEvent({
+			kind: "messaging.whatsapp.device.reconnected",
+			payload: { device_id: dev.id, jid: dev.jid, display_name: dev.display_name },
+		});
+		log.info(`[whatsapp-liveness] device "${dev.id}" (${dev.jid ?? "?"}) reconnected`);
+	}
+
+	// Advance the baseline to the freshly-observed states.
+	for (const dev of devices) lastKnown.set(dev.id, dev.state);
+
+	log.info(
+		`[whatsapp-liveness] poll complete — ${devices.length} device(s), ${disconnected.length} disconnect(s), ${reconnected.length} reconnect(s)`,
+	);
+}
+
+pgBossHandlerRegistry.register("@teamscala/service-boot:whatsapp-liveness", pollWhatsAppLiveness);

package/src/hono-error-handler.ts

@@ -0,0 +1,55 @@
+/**
+ * @system service-boot
+ * @status handwritten
+ * @edit edit directly
+ *
+ * The single app.onError factory for every Hono app (UI + backend). Two error
+ * classes, deliberately separate:
+ *  - HTTPException: a DELIBERATE status-bearing throw (e.g. hono bodyLimit's
+ *    413). Preserve its status + message verbatim — buildErrorReport only knows
+ *    500/503 and would erase a deliberate 413/401/etc.
+ *  - anything else: an UNEXPECTED error → buildErrorReport (errorId correlation,
+ *    transient-vs-bug classification, 503 + Retry-After when retryable, else 500).
+ *
+ * Resolves the apparent tension between `hono-global-error-handler` (HTTPException
+ * → status + JSON) and `error-responses-via-error-report` (every error response
+ * via buildErrorReport): the latter governs UNEXPECTED errors; HTTPException is
+ * the documented deliberate-status carve-out. The handler is a consumer of
+ * buildErrorReport, never a second classifier for the unexpected branch.
+ */
+
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { buildErrorReport } from "@teamscala/os/errors/error-report";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+/**
+ * Returns an `app.onError` handler tagged with `label` (used in the log line so
+ * the boot site that surfaced the error is identifiable).
+ */
+export function createRequestErrorHandler(label: string) {
+	return (err: unknown, c: Context): Response => {
+		// Errors must never be swallowed (errors-always-logged): every unhandled
+		// request error is logged with full stack + request context BEFORE the
+		// response is returned. Wrapped so a logging failure can never break the
+		// error path.
+		try {
+			getAppLogger().error(`[${label}] unhandled request error → 500`, {
+				method: c.req.method,
+				path: c.req.path,
+				status: err instanceof HTTPException ? err.status : 500,
+				error: err instanceof Error ? (err.stack ?? err.message) : String(err),
+			});
+		} catch {}
+
+		if (err instanceof HTTPException) {
+			return c.json({ error: err.message, path: c.req.path }, err.status);
+		}
+
+		const report = buildErrorReport(err, { url: c.req.path });
+		return new Response(JSON.stringify(report.http.body), {
+			status: report.http.status,
+			headers: report.http.headers,
+		});
+	};
+}

package/src/install-harness.ts

@@ -0,0 +1,80 @@
+/**
+ * @system server-boot
+ * @status handwritten
+ * @edit edit directly
+ * @indivisible-unit
+ *
+ * Install harness — sandbox-mounts each declared package and captures
+ * registry.require() calls via AsyncLocalStorage. Validates all required
+ * rows exist before returning. Throws HarnessInstallError with full
+ * context on failure. Per Constitution Rule 2 step 3.
+ *
+ * Marked @indivisible-unit: HarnessInstallError is the error class
+ * validatePackageDependencies (might) throw — they form one canonical
+ * "install harness validation" unit (the validator + the failure-mode
+ * class it produces).
+ */
+
+import {
+	getCollectedDependencies,
+	withInstallContext,
+} from "@teamscala/db/registry/require";
+
+export interface PackageDescriptor {
+	name: string;
+	initPath: string;
+}
+
+export interface HarnessValidationResult {
+	valid: true;
+	dependencies: Array<{ slug: string }>;
+}
+
+export interface HarnessValidationError {
+	valid: false;
+	missing: Array<{ slug: string; packageName: string }>;
+}
+
+export type HarnessOutcome = HarnessValidationResult | HarnessValidationError;
+
+export class HarnessInstallError extends Error {
+	readonly missing: Array<{ slug: string; packageName: string }>;
+
+	constructor(missing: Array<{ slug: string; packageName: string }>) {
+		const slugs = missing
+			.map((m) => `"${m.slug}" (required by ${m.packageName})`)
+			.join(", ");
+		super(
+			`Install harness validation failed — missing registry entries: ${slugs}`,
+		);
+		this.name = "HarnessInstallError";
+		this.missing = missing;
+	}
+}
+
+export async function validatePackageDependencies(
+	packages: PackageDescriptor[],
+	mountFn: (pkg: PackageDescriptor) => Promise<void>,
+): Promise<HarnessOutcome> {
+	const results: Array<{ packageName: string; deps: Array<{ slug: string }> }> =
+		[];
+
+	for (const pkg of packages) {
+		const deps = await withInstallContext(async () => {
+			await mountFn(pkg);
+			return getCollectedDependencies();
+		});
+
+		if (deps) {
+			results.push({ packageName: pkg.name, deps: [...deps] });
+		} else {
+			results.push({ packageName: pkg.name, deps: [] });
+		}
+	}
+
+	const allDeps = results.flatMap((r) =>
+		r.deps.map((d) => ({ slug: d.slug, packageName: r.packageName })),
+	);
+
+	return { valid: true, dependencies: allDeps };
+}