feat(video): add validated focus windows

docs/openapi.yaml

@@ -5508,6 +5508,28 @@ paths:
             type: integer
             minimum: 1
             maximum: 16
+        - in: query
+          name: samplingPolicy
+          required: false
+          description: Optional deterministic sampling policy. Scene-aware detection falls back to uniform sampling on detector failure.
+          schema:
+            type: string
+            enum: [uniform, scene_aware]
+            default: uniform
+        - in: query
+          name: start
+          required: false
+          description: Optional focus-window start in seconds. The broker clamps it to the media duration.
+          schema:
+            type: number
+            minimum: 0
+        - in: query
+          name: end
+          required: false
+          description: Optional focus-window end in seconds. It must be greater than the normalized start.
+          schema:
+            type: number
+            minimum: 0
       requestBody:
         required: true
         content:

docs/security/GUARDRAILS.md

@@ -313,7 +313,13 @@ never receives a URL. Sampling is `uniform` by default. The optional
 validated local stream, selects bounded `showinfo` scene timestamps, and falls
 back deterministically to the same uniform midpoints on detector failure,
 timeout, malformed output, or an empty candidate set. The hard 16-frame cap is
-applied after selection in every policy.
+applied after selection in every policy. A caller may optionally provide a
+finite focus window (`start`/`end` seconds); bounds are clamped to the media
+duration, reversed or non-finite windows are rejected, and uniform/scene-aware
+sampling is performed only inside the normalized interval. The resulting
+window is included in sampling metadata and in the untrusted description
+prefix so downstream models can distinguish a focused excerpt from the full
+timeline.
 Each frame is limited to 4 MiB, all raw frames together to 23 MiB, and the
 serialized broker response to 32 MiB. A private temporary directory is removed
 in `finally`. OmniRoute does not bundle FFmpeg and does not accept a custom