feat: wave-3 video surfaces — lipsync, video matte, video upscale, chain jobs (ADR-0025)

- videogen.LipSyncer/LipsyncProvider: SadTalker talking heads via
  POST /upstream/<id>/v1/talking_head (multipart image+audio parts,
  still/enhance/preprocess flags) -> mp4.
- videogen.VideoBackgroundRemover/VideoBackgroundRemovalProvider:
  POST /upstream/<id>/v1/video/matte (output greenscreen_mp4|alpha_webm).
- videogen.VideoUpscaler/VideoUpscaleProvider:
  POST /upstream/<id>/v1/video/upscale (scale 2|4).
- videogen.Chainer/ChainerProvider: async long-video chain-job client —
  SubmitChain (JSON POST /v1/video/chain, init_image_b64), ChainStatus
  (GET /v1/jobs/{id}, tolerant segment-id decode), ChainResult,
  ChainSegmentResult (partial delivery after mid-chain failure); hostile
  job-id path rejection.
- Shared singleVideoResult validation (positive video evidence) + a
  videoInputFilename hint helper; httptest contract tests per surface;
  ADR-0025 (index row deferred — MJ-A backfills the ADR index table and
  parallel edits would conflict).

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

videogen/vupscale.go

@@ -0,0 +1,74 @@
+package videogen
+
+import "context"
+
+// VideoUpscaleRequest asks a super-resolution backend (per-frame Real-ESRGAN
+// style) to enlarge a clip. Zero values mean "backend default" (ADR-0025).
+type VideoUpscaleRequest struct {
+	// Video is the encoded clip to upscale. Required. Carried as bytes
+	// (never a URL).
+	Video []byte
+
+	// MIME is the video MIME type (e.g. "video/mp4"); "" = let the backend
+	// sniff it.
+	MIME string
+
+	// Filename is the multipart filename hint some backends key their format
+	// detection on; "" derives one from MIME ("video.mp4") or falls back to
+	// "video".
+	Filename string
+
+	// Scale is the enlargement factor (2 or 4 on the reference backend);
+	// 0 = backend default.
+	Scale int
+}
+
+// VideoUpscaleOption mutates a VideoUpscaleRequest before it is sent.
+type VideoUpscaleOption func(*VideoUpscaleRequest)
+
+// WithVideoUpscaleScale sets the enlargement factor.
+func WithVideoUpscaleScale(s int) VideoUpscaleOption {
+	return func(r *VideoUpscaleRequest) { r.Scale = s }
+}
+
+// Apply returns a copy of the request with all options applied.
+func (r VideoUpscaleRequest) Apply(opts ...VideoUpscaleOption) VideoUpscaleRequest {
+	for _, opt := range opts {
+		opt(&r)
+	}
+	return r
+}
+
+// VideoUpscaler enlarges video clips frame by frame — the moving-picture
+// sibling of imagegen.Upscaler.
+type VideoUpscaler interface {
+	// UpscaleVideo returns the enlarged clip. Upscaling is slow (per-frame
+	// inference); bound the call with a context deadline.
+	UpscaleVideo(ctx context.Context, req VideoUpscaleRequest, opts ...VideoUpscaleOption) (*Result, error)
+}
+
+// VideoUpscalerModelOption configures a VideoUpscaler at construction time.
+// Reserved for future per-model settings.
+type VideoUpscalerModelOption func(*VideoUpscalerModelConfig)
+
+// VideoUpscalerModelConfig carries per-model construction settings.
+type VideoUpscalerModelConfig struct{}
+
+// ApplyVideoUpscalerModelOptions folds options into a config.
+func ApplyVideoUpscalerModelOptions(opts []VideoUpscalerModelOption) VideoUpscalerModelConfig {
+	var cfg VideoUpscalerModelConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
+// VideoUpscaleProvider mints VideoUpscalers bound to one backend.
+type VideoUpscaleProvider interface {
+	// Name is the registry identifier for the provider.
+	Name() string
+
+	// VideoUpscalerModel returns a VideoUpscaler bound to the given id
+	// (passed through to the backend verbatim; no catalog validation).
+	VideoUpscalerModel(id string, opts ...VideoUpscalerModelOption) (VideoUpscaler, error)
+}