feat(faceswap): carry the measured outcome, not just the image

A face swap always returns an image and always looks like success. Whether the
likeness actually transferred is a different question, and until now nothing in
the response answered it — so a caller wanting to know went and asked a vision
model instead. That is wrong in precisely the cases that matter: shown a jogger
in a Georgetown cap holding McDonald's cups, a VLM answers "Bill Clinton"
whoever's face is on him. In the run that prompted this it reported failure on
six consecutive CORRECT swaps (measured afterwards at 0.79-0.84 cosine), and
the caller burned 21 minutes chasing a problem that did not exist.

Result.SwappedFaces now carries, per replaced face: pixel size, the target
image's dimensions, head yaw, and cosine similarity between the source face and
the face actually present in the output.

Yaw and FractionOfImage are the two that explain the complaint. The swap in
question replaced a 138px face in a 1010px-wide photo — 14% of the width,
correct and invisible at a glance — and elsewhere a face turned -82 degrees,
where the features carrying identity are edge-on and any swap reads as a
generic person. Same code on a 168px face in a 385px picture (44%, yaw 2) is
unmistakable. None of that was inferable from a bounding box.

Typed on Result rather than stuffed into Raw: a caller has to act on this, and
a value reachable only by type-asserting an `any` is one nobody finds in time.

doRawHeaders is doRaw with the whole header instead of only Content-Type; doRaw
delegates to it, so the other 25 call sites are untouched and there is still
one place where the status check and the size cap live.

A missing or malformed header yields nil, not an error — an older shim sends no
header, and a swap that produced a good image must not fail because the
diagnostics beside it were unreadable. Covered for absent/garbage/wrong-type,
and the parse is break-checked.

provider/llamaswap/audio.go

@@ -338,27 +338,41 @@ func parseVoices(raw []byte) ([]string, error) {
 // varies. contentType sets the request Content-Type when body is non-nil.
 // A response larger than maxBytes is an error, never a silent truncation.
 func (p *Provider) doRaw(ctx context.Context, method, path, model, contentType string, body io.Reader, maxBytes int64) ([]byte, string, error) {
-	if err := p.requireBaseURL(); err != nil {
+	data, hdr, err := p.doRawHeaders(ctx, method, path, model, contentType, body, maxBytes)
+	if err != nil {
 		return nil, "", err
 	}
+	return data, hdr.Get("Content-Type"), nil
+}
+
+// doRawHeaders is doRaw with the WHOLE response header rather than just
+// Content-Type. Only the face swap needs it — the shim reports whether the
+// likeness actually transferred in X-Swap-Report, and that answer would be
+// thrown away by a function that keeps one header — so doRaw stays the
+// signature 25 other call sites use and delegates here. Two bodies would be
+// two places for the size cap and the status check to drift apart.
+func (p *Provider) doRawHeaders(ctx context.Context, method, path, model, contentType string, body io.Reader, maxBytes int64) ([]byte, http.Header, error) {
+	if err := p.requireBaseURL(); err != nil {
+		return nil, nil, err
+	}
 	req, err := p.newRequest(ctx, method, path, contentType, body)
 	if err != nil {
-		return nil, "", err
+		return nil, nil, err
 	}
 	resp, err := p.client.Do(req)
 	if err != nil {
-		return nil, "", fmt.Errorf("llama-swap: do request: %w", err)
+		return nil, nil, fmt.Errorf("llama-swap: do request: %w", err)
 	}
 	defer resp.Body.Close()
 	if resp.StatusCode/100 != 2 {
-		return nil, "", p.apiError(resp, model)
+		return nil, nil, p.apiError(resp, model)
 	}
 	data, err := io.ReadAll(io.LimitReader(resp.Body, maxBytes+1))
 	if err != nil {
-		return nil, "", fmt.Errorf("llama-swap: read response: %w", err)
+		return nil, nil, fmt.Errorf("llama-swap: read response: %w", err)
 	}
 	if int64(len(data)) > maxBytes {
-		return nil, "", fmt.Errorf("llama-swap: response exceeds %d bytes", maxBytes)
+		return nil, nil, fmt.Errorf("llama-swap: response exceeds %d bytes", maxBytes)
 	}
-	return data, resp.Header.Get("Content-Type"), nil
+	return data, resp.Header, nil
 }

provider/llamaswap/faceswap.go

@@ -126,10 +126,11 @@ func (m *faceSwapModel) FaceSwap(ctx context.Context, req imagegen.FaceSwapReque
 	if err != nil {
 		return nil, err
 	}
-	raw, respType, err := m.p.doRaw(ctx, http.MethodPost, path, m.id, contentType, body, maxFaceSwapResponseBytes)
+	raw, respHdr, err := m.p.doRawHeaders(ctx, http.MethodPost, path, m.id, contentType, body, maxFaceSwapResponseBytes)
 	if err != nil {
 		return nil, err
 	}
+	respType := respHdr.Get("Content-Type")
 	if len(raw) == 0 {
 		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "face swap response contained no image"}
 	}
@@ -151,7 +152,55 @@ func (m *faceSwapModel) FaceSwap(ctx context.Context, req imagegen.FaceSwapReque
 	if hdr := mimeFromContentType(respType, "image/"); hdr != "" {
 		mimeType = hdr
 	}
-	return &imagegen.Result{Images: []llm.ImagePart{{MIME: mimeType, Data: raw}}}, nil
+	return &imagegen.Result{
+		Images:       []llm.ImagePart{{MIME: mimeType, Data: raw}},
+		SwappedFaces: parseSwapReport(respHdr.Get("X-Swap-Report")),
+	}, nil
+}
+
+// swapReport mirrors the shim's X-Swap-Report header.
+type swapReport struct {
+	Image []int `json:"image"`
+	Faces []struct {
+		Index              int      `json:"index"`
+		Size               []int    `json:"size"`
+		Yaw                *float64 `json:"yaw"`
+		IdentitySimilarity *float64 `json:"identity_similarity"`
+	} `json:"faces"`
+}
+
+// parseSwapReport decodes the measured outcome. A missing or malformed header
+// yields nil rather than an error: an older shim does not send it, and a swap
+// that produced a good image must not fail because the diagnostics alongside
+// it were unreadable.
+func parseSwapReport(header string) []imagegen.SwappedFace {
+	header = strings.TrimSpace(header)
+	if header == "" {
+		return nil
+	}
+	var rep swapReport
+	if err := json.Unmarshal([]byte(header), &rep); err != nil {
+		return nil
+	}
+	out := make([]imagegen.SwappedFace, 0, len(rep.Faces))
+	for _, f := range rep.Faces {
+		sf := imagegen.SwappedFace{
+			Index:              f.Index,
+			Yaw:                f.Yaw,
+			IdentitySimilarity: f.IdentitySimilarity,
+		}
+		if len(f.Size) == 2 {
+			sf.Width, sf.Height = f.Size[0], f.Size[1]
+		}
+		if len(rep.Image) == 2 {
+			sf.ImageWidth, sf.ImageHeight = rep.Image[0], rep.Image[1]
+		}
+		out = append(out, sf)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
 }
 
 // imageFilename picks a multipart filename for an image part. The shim reads

provider/llamaswap/faceswap_test.go

@@ -259,3 +259,86 @@ func TestFaceSwapAllowsNegativeIndexUnderAll(t *testing.T) {
 		t.Error("negative index accepted when it would actually be sent")
 	}
 }
+
+// TestFaceSwapParsesSwapReport: the measured outcome is the whole reason the
+// header exists — a caller that cannot tell "the likeness transferred" from
+// "an image came back" goes and asks a vision model, which is wrong in
+// exactly the cases that matter.
+func TestFaceSwapParsesSwapReport(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "image/png")
+		w.Header().Set("X-Swap-Report",
+			`{"image":[1010,1200],"faces":[{"index":2,"size":[138,172],"yaw":-82.2,"identity_similarity":0.791}]}`)
+		raw, _ := base64.StdEncoding.DecodeString(onePixelPNG)
+		_, _ = w.Write(raw)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	m, err := p.FaceSwapModel("faceswap")
+	if err != nil {
+		t.Fatalf("model: %v", err)
+	}
+	img := editInit(t)
+	res, err := m.FaceSwap(context.Background(), imagegen.FaceSwapRequest{Target: img, Source: img})
+	if err != nil {
+		t.Fatalf("FaceSwap: %v", err)
+	}
+	if len(res.SwappedFaces) != 1 {
+		t.Fatalf("SwappedFaces = %d, want 1 — the measurement was dropped", len(res.SwappedFaces))
+	}
+	f := res.SwappedFaces[0]
+	if f.Index != 2 || f.Width != 138 || f.Height != 172 {
+		t.Errorf("face = %+v, want index 2 at 138x172", f)
+	}
+	if f.Yaw == nil || *f.Yaw != -82.2 {
+		t.Errorf("yaw = %v, want -82.2 — the pose signal is how a caller knows a profile swap will not read", f.Yaw)
+	}
+	if f.IdentitySimilarity == nil || *f.IdentitySimilarity != 0.791 {
+		t.Errorf("identity_similarity = %v, want 0.791", f.IdentitySimilarity)
+	}
+	// 138/1010 — the number that says "correct, and invisible at a glance".
+	if got := f.FractionOfImage(); got < 0.13 || got > 0.14 {
+		t.Errorf("FractionOfImage = %.3f, want ~0.137", got)
+	}
+}
+
+// TestFaceSwapSurvivesMissingReport: an older shim sends no header at all. A
+// swap that produced a good image must not fail because the diagnostics
+// beside it were absent or malformed.
+func TestFaceSwapSurvivesMissingReport(t *testing.T) {
+	for name, hdr := range map[string]string{
+		"absent":    "",
+		"garbage":   "not json at all",
+		"wrongtype": `{"faces":"nope"}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "image/png")
+				if hdr != "" {
+					w.Header().Set("X-Swap-Report", hdr)
+				}
+				raw, _ := base64.StdEncoding.DecodeString(onePixelPNG)
+				_, _ = w.Write(raw)
+			}))
+			defer srv.Close()
+
+			p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+			m, err := p.FaceSwapModel("faceswap")
+			if err != nil {
+				t.Fatalf("model: %v", err)
+			}
+			img := editInit(t)
+			res, err := m.FaceSwap(context.Background(), imagegen.FaceSwapRequest{Target: img, Source: img})
+			if err != nil {
+				t.Fatalf("a %s report failed the whole swap: %v", name, err)
+			}
+			if len(res.Images) != 1 {
+				t.Fatal("image lost")
+			}
+			if res.SwappedFaces != nil {
+				t.Errorf("SwappedFaces = %+v, want nil for a %s report", res.SwappedFaces, name)
+			}
+		})
+	}
+}