fix(housekeeping): complete people workflow fidelity

src/features/housekeeping/foundation/commands/dispatcher.ts

@@ -5,15 +5,12 @@ import { satisfiesCapability } from "../capability-context";
 import {
 	fail,
 	type HousekeepingCapabilityContext,
+	type HousekeepingPartialCompletion,
 	type HousekeepingResult,
 	mapUnknownError,
 } from "../contracts";
 import { createCorrelationId } from "../correlation";
-import {
-	AuditOutcomePersistenceError,
-	writeIntent,
-	writeOutcome,
-} from "./audit-envelope";
+import { writeIntent, writeOutcome } from "./audit-envelope";
 import { confirmHousekeepingCommand } from "./confirmation";
 import {
 	getHousekeepingCommand,
@@ -62,11 +59,25 @@ const housekeepingResultSchema = z.discriminatedUnion("ok", [
 		ok: z.literal(true),
 		data: z.unknown(),
 		correlationId: z.string().min(1).max(160),
+		completion: z
+			.strictObject({
+				status: z.literal("partial"),
+				external: z.enum(["not-required", "completed", "failed"]),
+				audit: z.enum(["persisted", "unavailable"]),
+			})
+			.optional(),
 	}),
 	z.strictObject({
 		ok: z.literal(false),
 		error: housekeepingErrorSchema,
 		correlationId: z.string().min(1).max(160),
+		completion: z
+			.strictObject({
+				status: z.literal("partial"),
+				external: z.enum(["not-required", "completed", "failed"]),
+				audit: z.enum(["persisted", "unavailable"]),
+			})
+			.optional(),
 	}),
 ]);
 
@@ -295,6 +306,13 @@ export async function dispatchHousekeepingCommand(
 			correlatedResult,
 		);
 	}
+	if (correlatedResult.completion?.status === "partial") {
+		return persistPartialCompletionOutcome(
+			dependencies.audit,
+			auditEntry,
+			correlatedResult,
+		);
+	}
 	return persistSuccessfulOutcome(
 		dependencies.audit,
 		auditEntry,
@@ -455,17 +473,49 @@ async function persistReturnedOutcome<T>(
 async function persistSuccessfulOutcome<T>(
 	writer: HousekeepingAuditWriter,
 	entry: AuditEntry,
-	result: HousekeepingResult<T>,
+	result: Extract<HousekeepingResult<T>, { ok: true }>,
 ): Promise<HousekeepingResult<T>> {
 	try {
 		await writeOutcome(writer, entry, "success");
 		return result;
-	} catch (auditOutcomeError) {
+	} catch {
+		let audit: HousekeepingPartialCompletion["audit"] = "persisted";
 		try {
 			await writeOutcome(writer, entry, "partial");
 		} catch {
-			// The completed-operation error below remains the primary evidence.
+			audit = "unavailable";
 		}
-		throw new AuditOutcomePersistenceError(result, auditOutcomeError);
+		return withPartialCompletion(result, {
+			status: "partial",
+			external: result.completion?.external ?? "not-required",
+			audit,
+		});
 	}
 }
+
+async function persistPartialCompletionOutcome<T>(
+	writer: HousekeepingAuditWriter,
+	entry: AuditEntry,
+	result: Extract<HousekeepingResult<T>, { ok: true }>,
+): Promise<HousekeepingResult<T>> {
+	try {
+		await writeOutcome(writer, entry, "partial");
+		return result;
+	} catch {
+		return withPartialCompletion(result, {
+			...(result.completion ?? {
+				status: "partial",
+				external: "not-required",
+				audit: "unavailable",
+			}),
+			audit: "unavailable",
+		});
+	}
+}
+
+function withPartialCompletion<T>(
+	result: Extract<HousekeepingResult<T>, { ok: true }>,
+	completion: HousekeepingPartialCompletion,
+): HousekeepingResult<T> {
+	return { ...result, completion };
+}