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/colorize.go

@@ -0,0 +1,54 @@
+package imagegen
+
+import "context"
+
+// ColorizeRequest asks a colorization backend (DDColor style) to add color to
+// a grayscale/faded photo (ADR-0023).
+type ColorizeRequest struct {
+	// Image is the image to colorize. Required.
+	Image Image
+}
+
+// ColorizeOption mutates a ColorizeRequest before it is sent. Reserved for
+// future request settings (the reference backend takes no parameters).
+type ColorizeOption func(*ColorizeRequest)
+
+// Apply returns a copy of the request with all options applied.
+func (r ColorizeRequest) Apply(opts ...ColorizeOption) ColorizeRequest {
+	for _, opt := range opts {
+		opt(&r)
+	}
+	return r
+}
+
+// Colorizer adds color to grayscale images.
+type Colorizer interface {
+	// Colorize returns the colorized image as a one-image Result.
+	Colorize(ctx context.Context, req ColorizeRequest, opts ...ColorizeOption) (*Result, error)
+}
+
+// ColorizeModelOption configures a Colorizer at construction time. Reserved
+// for future per-model settings.
+type ColorizeModelOption func(*ColorizeModelConfig)
+
+// ColorizeModelConfig carries per-model construction settings.
+type ColorizeModelConfig struct{}
+
+// ApplyColorizeModelOptions folds options into a config.
+func ApplyColorizeModelOptions(opts []ColorizeModelOption) ColorizeModelConfig {
+	var cfg ColorizeModelConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
+// ColorizeProvider mints Colorizers bound to one backend.
+type ColorizeProvider interface {
+	// Name is the registry identifier for the provider.
+	Name() string
+
+	// ColorizeModel returns a Colorizer bound to the given id (passed through
+	// to the backend verbatim; no catalog validation).
+	ColorizeModel(id string, opts ...ColorizeModelOption) (Colorizer, error)
+}

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)
+}

imagegen/segment.go

@@ -0,0 +1,70 @@
+package imagegen
+
+import "context"
+
+// SegmentationRequest asks a promptable-segmentation backend (GroundingDINO +
+// SAM style) for the mask of a text-described region. Zero values mean
+// "backend default" (ADR-0023).
+type SegmentationRequest struct {
+	// Image is the image to segment. Required.
+	Image Image
+
+	// Prompt is the text description of the region to segment (e.g. "the red
+	// car"). Required — promptless segmentation is a different capability.
+	Prompt string
+
+	// Threshold is the detection confidence threshold in (0,1]; 0 = backend
+	// default.
+	Threshold float64
+}
+
+// SegmentationOption mutates a SegmentationRequest before it is sent.
+type SegmentationOption func(*SegmentationRequest)
+
+// WithSegmentationThreshold sets the detection confidence threshold.
+func WithSegmentationThreshold(t float64) SegmentationOption {
+	return func(r *SegmentationRequest) { r.Threshold = t }
+}
+
+// Apply returns a copy of the request with all options applied.
+func (r SegmentationRequest) Apply(opts ...SegmentationOption) SegmentationRequest {
+	for _, opt := range opts {
+		opt(&r)
+	}
+	return r
+}
+
+// Segmenter extracts a prompted region's mask from an image. The result is a
+// single grayscale mask image where WHITE marks the prompted region — the
+// same polarity as EditRequest.Mask (white = repaint), so it feeds inpainting
+// directly; derive a cutout client-side by applying the mask as alpha.
+type Segmenter interface {
+	// Segment returns the region mask as a one-image Result.
+	Segment(ctx context.Context, req SegmentationRequest, opts ...SegmentationOption) (*Result, error)
+}
+
+// SegmentationModelOption configures a Segmenter at construction time.
+// Reserved for future per-model settings (mirrors ModelOption).
+type SegmentationModelOption func(*SegmentationModelConfig)
+
+// SegmentationModelConfig carries per-model construction settings.
+type SegmentationModelConfig struct{}
+
+// ApplySegmentationModelOptions folds options into a config.
+func ApplySegmentationModelOptions(opts []SegmentationModelOption) SegmentationModelConfig {
+	var cfg SegmentationModelConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
+// SegmentationProvider mints Segmenters bound to one backend.
+type SegmentationProvider interface {
+	// Name is the registry identifier for the provider.
+	Name() string
+
+	// SegmentationModel returns a Segmenter bound to the given id (passed
+	// through to the backend verbatim; no catalog validation).
+	SegmentationModel(id string, opts ...SegmentationModelOption) (Segmenter, error)
+}