feat: wave-3 image + document surfaces — segmentation, colorize, face restore, ocr (ADR-0023)

- imagegen.Segmenter/SegmentationProvider: prompted mask via
  POST /upstream/<id>/v1/segment (file, prompt[, threshold], output=mask);
  white = prompted region, EditRequest.Mask polarity.
- imagegen.Colorizer/ColorizeProvider: POST /upstream/<id>/v1/colorize.
- imagegen.FaceRestorer/FaceRestoreProvider:
  POST /upstream/<id>/v1/restore_faces (upscale 1|2).
- New ocr leaf package (Request/Page/Result, Recognize) + llamaswap
  OCRModel: POST /upstream/<id>/v1/ocr (file[, langs, max_pages]),
  tolerant per-page decode (join lines when page text absent), Raw
  escape hatch.
- httptest contract tests per surface; ADR-0023; ADR index backfilled
  (0020-0022 rows were missing).

Co-Authored-By: Claude Fable 5 <[email protected]>

imagegen/facerestore.go

@@ -0,0 +1,62 @@
+package imagegen
+
+import "context"
+
+// FaceRestoreRequest asks a face-restoration backend (GFPGAN style) to repair
+// degraded faces in a photo. Zero values mean "backend default" (ADR-0023).
+type FaceRestoreRequest struct {
+	// Image is the image to restore. Required.
+	Image Image
+
+	// Upscale is the output enlargement factor (1 or 2 on the reference
+	// backend); 0 = backend default.
+	Upscale int
+}
+
+// FaceRestoreOption mutates a FaceRestoreRequest before it is sent.
+type FaceRestoreOption func(*FaceRestoreRequest)
+
+// WithFaceRestoreUpscale sets the output enlargement factor.
+func WithFaceRestoreUpscale(n int) FaceRestoreOption {
+	return func(r *FaceRestoreRequest) { r.Upscale = n }
+}
+
+// Apply returns a copy of the request with all options applied.
+func (r FaceRestoreRequest) Apply(opts ...FaceRestoreOption) FaceRestoreRequest {
+	for _, opt := range opts {
+		opt(&r)
+	}
+	return r
+}
+
+// FaceRestorer repairs degraded/blurry faces in photos.
+type FaceRestorer interface {
+	// RestoreFaces returns the restored image as a one-image Result.
+	RestoreFaces(ctx context.Context, req FaceRestoreRequest, opts ...FaceRestoreOption) (*Result, error)
+}
+
+// FaceRestoreModelOption configures a FaceRestorer at construction time.
+// Reserved for future per-model settings.
+type FaceRestoreModelOption func(*FaceRestoreModelConfig)
+
+// FaceRestoreModelConfig carries per-model construction settings.
+type FaceRestoreModelConfig struct{}
+
+// ApplyFaceRestoreModelOptions folds options into a config.
+func ApplyFaceRestoreModelOptions(opts []FaceRestoreModelOption) FaceRestoreModelConfig {
+	var cfg FaceRestoreModelConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
+// FaceRestoreProvider mints FaceRestorers bound to one backend.
+type FaceRestoreProvider interface {
+	// Name is the registry identifier for the provider.
+	Name() string
+
+	// FaceRestoreModel returns a FaceRestorer bound to the given id (passed
+	// through to the backend verbatim; no catalog validation).
+	FaceRestoreModel(id string, opts ...FaceRestoreModelOption) (FaceRestorer, error)
+}