fix(housekeeping): preserve error correlation IDs

src/features/housekeeping/foundation/contracts/contracts.test.ts

@@ -145,13 +145,34 @@ describe("housekeeping foundation contracts", () => {
 		});
 	});
 
-	it("sanitizes unknown errors with the stable internal taxonomy", () => {
-		expect(mapUnknownError(new Error("database password exposed"))).toEqual({
-			code: "INTERNAL",
-			messageKey: "errors.housekeeping.internal",
+	it("preserves a supplied correlation ID when mapping an unknown error", () => {
+		expect(
+			mapUnknownError(new Error("database password exposed"), "corr-unknown"),
+		).toEqual({
+			ok: false,
+			error: {
+				code: "INTERNAL",
+				messageKey: "errors.housekeeping.internal",
+			},
+			correlationId: "corr-unknown",
 		});
 	});
 
+	it("generates a correlation ID when mapping an unknown error without one", () => {
+		const result = mapUnknownError(new Error("database password exposed"));
+
+		expect(result).toMatchObject({
+			ok: false,
+			error: {
+				code: "INTERNAL",
+				messageKey: "errors.housekeeping.internal",
+			},
+		});
+		expect(result.correlationId).toMatch(
+			/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+		);
+	});
+
 	it("rejects empty capability requirements", () => {
 		expect(() => anyCapability()).toThrow("capability requirement is empty");
 		expect(() => allCapabilities()).toThrow("capability requirement is empty");

src/features/housekeeping/foundation/contracts/result.ts

@@ -1,3 +1,5 @@
+import { createCorrelationId } from "../correlation";
+
 export type HousekeepingErrorCode =
 	| "UNAUTHENTICATED"
 	| "FORBIDDEN"
@@ -40,9 +42,9 @@ export function fail(
 	};
 }
 
-export function mapUnknownError(_error: unknown): HousekeepingError {
-	return {
-		code: "INTERNAL",
-		messageKey: "errors.housekeeping.internal",
-	};
+export function mapUnknownError(
+	_error: unknown,
+	correlationId = createCorrelationId(),
+): HousekeepingResult<never> {
+	return fail("INTERNAL", "errors.housekeeping.internal", correlationId);
 }