refactor(housekeeping): stabilize service contracts

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

@@ -1,20 +1,23 @@
 export type HousekeepingErrorCode =
-	| "VALIDATION_FAILED"
-	| "AUTHENTICATION_REQUIRED"
-	| "CAPABILITY_DENIED"
+	| "UNAUTHENTICATED"
+	| "FORBIDDEN"
+	| "VALIDATION"
 	| "NOT_FOUND"
 	| "CONFLICT"
+	| "RATE_LIMITED"
 	| "DEPENDENCY_UNAVAILABLE"
-	| "PARTIAL_RESULT"
-	| "INTERNAL_ERROR";
+	| "TIMEOUT"
+	| "INTERNAL";
+
+export interface HousekeepingError {
+	code: HousekeepingErrorCode;
+	messageKey: string;
+	fieldErrors?: Readonly<Record<string, readonly string[]>>;
+}
 
 export type HousekeepingResult<T> =
 	| { ok: true; data: T; correlationId: string }
-	| {
-			ok: false;
-			error: { code: HousekeepingErrorCode };
-			correlationId: string;
-	  };
+	| { ok: false; error: HousekeepingError; correlationId: string };
 
 export function ok<T>(data: T, correlationId: string): HousekeepingResult<T> {
 	return { ok: true, data, correlationId };
@@ -22,7 +25,24 @@ export function ok<T>(data: T, correlationId: string): HousekeepingResult<T> {
 
 export function fail(
 	code: HousekeepingErrorCode,
+	messageKey: string,
 	correlationId: string,
+	fieldErrors?: Readonly<Record<string, readonly string[]>>,
 ): HousekeepingResult<never> {
-	return { ok: false, error: { code }, correlationId };
+	return {
+		ok: false,
+		error: {
+			code,
+			messageKey,
+			...(fieldErrors === undefined ? {} : { fieldErrors }),
+		},
+		correlationId,
+	};
+}
+
+export function mapUnknownError(_error: unknown): HousekeepingError {
+	return {
+		code: "INTERNAL",
+		messageKey: "errors.housekeeping.internal",
+	};
 }