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