docs(changelog): link Video Bridge sampler PR

changelog.d/fixes/11344-video-bridge-scene-aware-sampler.md

@@ -0,0 +1 @@
+- **fix(video-bridge):** fall back to the deterministic active-window midpoint when a one-frame scene-aware budget cannot preserve both timeline ends; a real FFmpeg fixture matrix now covers rapid cuts, gradual changes, static and short clips, and detector failure ([#11344](https://github.com/diegosouzapw/OmniRoute/pull/11344)).

changelog.d/maintenance/11363-openapi-try-operation-coverage.md

@@ -1 +0,0 @@
-- **docs(openapi):** document the conditionally management-authenticated, same-origin `POST /api/openapi/try` proxy contract and restore the release branch's operation-coverage ratchet ([#11363](https://github.com/diegosouzapw/OmniRoute/pull/11363))

docs/openapi.yaml

@@ -6931,104 +6931,6 @@ paths:
         "500":
           description: Failed to parse OpenAPI spec
 
-  /api/openapi/try:
-    post:
-      tags: [System]
-      summary: Proxy an API Explorer request to an OmniRoute endpoint
-      description: >-
-        Executes an API Explorer request through a server-side, same-origin proxy. The target
-        must start with `/api/`, `/v1/`, `/v1beta/`, `/a2a`, or
-        `/.well-known/agent.json`; protocol-relative and cross-origin targets are rejected.
-        Hop-by-hop, proxy, host, cookie, and forwarding headers supplied in `headers` are
-        stripped, while any dashboard cookie on the original request is forwarded separately.
-        When `requireLogin` is disabled, the management-auth bypass mirrors the runtime setting;
-        otherwise a management Bearer credential or dashboard session is required. Failures
-        caught after authentication, including request JSON parsing, fetch, and response-body
-        parsing failures, are returned in the normal HTTP 200 result envelope so the Explorer
-        can display them; `status: 0` identifies that caught-failure path.
-      security:
-        - BearerAuth: []
-        - ManagementSessionAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required: [path]
-              properties:
-                method:
-                  type: string
-                  enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
-                  default: GET
-                path:
-                  type: string
-                  minLength: 1
-                  pattern: "^/(?:api/|v1/|v1beta/|a2a|\\.well-known/agent\\.json)"
-                  description: Same-origin OmniRoute API path, optionally including a query string.
-                headers:
-                  type: object
-                  default: {}
-                  additionalProperties:
-                    type: string
-                  description: >-
-                    Headers to forward after removing connection, content-length, cookie, host,
-                    keep-alive, proxy-authenticate, proxy-authorization, te, trailer,
-                    transfer-encoding, upgrade, x-forwarded-for, x-forwarded-host, and
-                    x-forwarded-proto headers.
-                body:
-                  description: >-
-                    Optional JSON value. A truthy value is serialized unless it is already a
-                    string, and is not forwarded when `method` is `GET`.
-      responses:
-        "200":
-          description: Upstream response or displayable caught-failure envelope
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: false
-                required: [status, statusText, headers, body, latencyMs, contentType]
-                properties:
-                  status:
-                    type: integer
-                    minimum: 0
-                    description: Upstream HTTP status, or 0 when request processing throws.
-                  statusText:
-                    type: string
-                  headers:
-                    type: object
-                    additionalProperties:
-                      type: string
-                  body:
-                    description: >-
-                      Parsed JSON, response text truncated after 10,000 characters, or a sanitized
-                      caught-error object.
-                  latencyMs:
-                    type: integer
-                    minimum: 0
-                  contentType:
-                    type: string
-        "400":
-          description: Invalid request body or non-same-origin path
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - $ref: "#/components/schemas/ValidationErrorResponse"
-                  - type: object
-                    required: [error]
-                    properties:
-                      error:
-                        type: string
-                        example: Path must be same-origin
-        "401":
-          $ref: "#/components/responses/ManagementAuthenticationRequired"
-        "403":
-          $ref: "#/components/responses/ManagementInvalidToken"
-        "503":
-          $ref: "#/components/responses/InternalError"
-
   # ─── Agent Skills Catalog ────────────────────────────────────────────────────
 
   /api/agent-skills:

docs/security/GUARDRAILS.md

@@ -328,7 +328,10 @@ fixed FFmpeg pass over the already validated local stream, select bounded
 uniform midpoints on detector failure, timeout, malformed output, or an empty
 candidate set. Segment-aware mode allocates midpoint samples proportionally to
 the validated scene intervals. The hard 16-frame cap is
-applied after selection in every policy. A caller may optionally provide a
+applied after selection in every policy. When a scene-aware request has only a
+one-frame budget, it uses the uniform midpoint of the active full-video or focus
+window and reports `policyEffective: uniform`: a single selected scene frame
+cannot preserve both temporal ends. 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 all sampling
 policies are performed only inside the normalized interval. The resulting

src/lib/guardrails/videoBridgeRuntime.ts

@@ -339,6 +339,15 @@ export function calculateSamplingDecision(
   }
 
   const frameCount = uniform.length;
+  if (frameCount === 1) {
+    return {
+      candidateCount: candidates.length,
+      ...(focusWindow ? { focusWindow } : {}),
+      policyEffective: "uniform",
+      policyRequested: "scene_aware",
+      timestamps: uniform,
+    };
+  }
   const selected =
     candidates.length <= frameCount
       ? [...candidates]

tests/integration/video-bridge-sampler-ffmpeg.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Real FFmpeg fixture gate for the scene-aware Video Bridge sampler.
+ *
+ * Run explicitly because FFmpeg is an optional operational dependency:
+ * RUN_VIDEO_BRIDGE_FFMPEG=1 node --import tsx/esm --test \
+ *   tests/integration/video-bridge-sampler-ffmpeg.test.ts
+ */
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+
+import {
+  extractVideoFramesFromBytes,
+  type VideoCommandRunner,
+} from "../../src/lib/guardrails/videoBridgeRuntime.ts";
+
+const execFileAsync = promisify(execFile);
+const REAL_FFMPEG_ENABLED = process.env.RUN_VIDEO_BRIDGE_FFMPEG === "1";
+const REAL_FFMPEG_SKIP = REAL_FFMPEG_ENABLED
+  ? false
+  : "Set RUN_VIDEO_BRIDGE_FFMPEG=1 to run the real FFmpeg fixture matrix";
+
+const realRunner: VideoCommandRunner = async (executable, args, options) => {
+  const result = await execFileAsync(executable, [...args], {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+    signal: options.signal,
+    timeout: options.timeoutMs,
+    windowsHide: true,
+  });
+  return { stderr: String(result.stderr), stdout: String(result.stdout) };
+};
+
+async function createFixture(
+  directory: string,
+  name: string,
+  inputArgs: readonly string[],
+  videoFilter: string
+): Promise<Buffer> {
+  const outputPath = join(directory, `${name}.mkv`);
+  await realRunner(
+    "ffmpeg",
+    [
+      "-nostdin",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      ...inputArgs,
+      "-vf",
+      videoFilter,
+      "-c:v",
+      "ffv1",
+      "-y",
+      outputPath,
+    ],
+    { timeoutMs: 30_000 }
+  );
+  return readFile(outputPath);
+}
+
+async function createRapidEdgeCutFixture(directory: string): Promise<Buffer> {
+  const outputPath = join(directory, "rapid-edge-cuts.mkv");
+  await realRunner(
+    "ffmpeg",
+    [
+      "-nostdin",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-f",
+      "lavfi",
+      "-i",
+      "color=c=red:s=64x64:r=10:d=0.2",
+      "-f",
+      "lavfi",
+      "-i",
+      "color=c=black:s=64x64:r=10:d=2.6",
+      "-f",
+      "lavfi",
+      "-i",
+      "color=c=white:s=64x64:r=10:d=0.2",
+      "-filter_complex",
+      "[0:v][1:v][2:v]concat=n=3:v=1:a=0,format=yuv420p[v]",
+      "-map",
+      "[v]",
+      "-c:v",
+      "ffv1",
+      "-y",
+      outputPath,
+    ],
+    { timeoutMs: 30_000 }
+  );
+  return readFile(outputPath);
+}
+
+async function sample(bytes: Buffer, frameCount: number, runner = realRunner) {
+  return extractVideoFramesFromBytes(bytes, {
+    frameCount,
+    maxDurationSeconds: 600,
+    runner,
+    samplingPolicy: "scene_aware",
+    timeoutMs: 30_000,
+  });
+}
+
+test(
+  "scene-aware sampling handles the canonical real FFmpeg fixture matrix",
+  { skip: REAL_FFMPEG_SKIP },
+  async (context) => {
+    const directory = await mkdtemp(join(tmpdir(), "omniroute-video-sampler-fixtures-"));
+    context.after(async () => rm(directory, { force: true, recursive: true }));
+
+    const rapidCuts = await createRapidEdgeCutFixture(directory);
+    await context.test("rapid cuts near both ends retain coverage within the cap", async () => {
+      const result = await sample(rapidCuts, 4);
+
+      assert.deepEqual(
+        result.frames.map((frame) => frame.timestampSeconds),
+        [0.2, 0.5, 2.8]
+      );
+      assert.deepEqual(result.sampling, {
+        candidateCount: 2,
+        policyEffective: "scene_aware",
+        policyRequested: "scene_aware",
+      });
+      assert.ok(result.frames.length <= 16);
+    });
+
+    await context.test("one frame falls back to the full-window midpoint", async () => {
+      const result = await sample(rapidCuts, 1);
+
+      assert.deepEqual(
+        result.frames.map((frame) => frame.timestampSeconds),
+        [1.5]
+      );
+      assert.deepEqual(result.sampling, {
+        candidateCount: 2,
+        policyEffective: "uniform",
+        policyRequested: "scene_aware",
+      });
+    });
+
+    const staticVideo = await createFixture(
+      directory,
+      "static",
+      ["-f", "lavfi", "-i", "color=c=blue:s=64x64:r=10:d=4"],
+      "format=yuv420p"
+    );
+    await context.test("a static scene falls back to uniform midpoints", async () => {
+      const result = await sample(staticVideo, 4);
+
+      assert.deepEqual(
+        result.frames.map((frame) => frame.timestampSeconds),
+        [0.5, 1.5, 2.5, 3.5]
+      );
+      assert.deepEqual(result.sampling, {
+        candidateCount: 0,
+        policyEffective: "uniform",
+        policyRequested: "scene_aware",
+      });
+    });
+
+    const slowChange = await createFixture(
+      directory,
+      "slow-change",
+      ["-f", "lavfi", "-i", "nullsrc=s=64x64:r=10:d=4"],
+      "geq=lum='clip(16+200*T/4,16,235)':cb=128:cr=128,format=yuv420p"
+    );
+    await context.test("a gradual luminance change does not become a false scene cut", async () => {
+      const result = await sample(slowChange, 4);
+
+      assert.deepEqual(
+        result.frames.map((frame) => frame.timestampSeconds),
+        [0.5, 1.5, 2.5, 3.5]
+      );
+      assert.equal(result.sampling.candidateCount, 0);
+      assert.equal(result.sampling.policyEffective, "uniform");
+    });
+
+    const shortVideo = await createFixture(
+      directory,
+      "short",
+      ["-f", "lavfi", "-i", "color=c=yellow:s=64x64:r=10:d=0.4"],
+      "format=yuv420p"
+    );
+    await context.test("a sub-second clip remains deterministic and bounded", async () => {
+      const result = await sample(shortVideo, 8);
+
+      assert.deepEqual(
+        result.frames.map((frame) => frame.timestampSeconds),
+        [0.2]
+      );
+      assert.equal(result.sampling.policyEffective, "uniform");
+    });
+
+    await context.test(
+      "a detector failure falls back while real frame extraction continues",
+      async () => {
+        const detectorFailureRunner: VideoCommandRunner = async (executable, args, options) => {
+          if (args.some((arg) => arg.includes("showinfo"))) {
+            throw new Error("fixture scene detector failure");
+          }
+          return realRunner(executable, args, options);
+        };
+        const result = await sample(staticVideo, 4, detectorFailureRunner);
+
+        assert.deepEqual(
+          result.frames.map((frame) => frame.timestampSeconds),
+          [0.5, 1.5, 2.5, 3.5]
+        );
+        assert.deepEqual(result.sampling, {
+          candidateCount: 0,
+          policyEffective: "uniform",
+          policyRequested: "scene_aware",
+        });
+      }
+    );
+  }
+);

tests/unit/guardrails/videoBridgeSampler.test.ts

@@ -29,6 +29,26 @@ test("scene-aware sampling falls back to deterministic uniform midpoints for a s
   assert.equal(decision.candidateCount, 0);
 });
 
+test("scene-aware sampling falls back to the midpoint when one frame cannot cover both ends", () => {
+  const decision = calculateSamplingDecision(8, 1, "scene_aware", [0.25, 7.75]);
+
+  assert.deepEqual(decision.timestamps, [4]);
+  assert.equal(decision.policyRequested, "scene_aware");
+  assert.equal(decision.policyEffective, "uniform");
+  assert.equal(decision.candidateCount, 2);
+});
+
+test("one-frame scene-aware fallback uses the active focus-window midpoint", () => {
+  const decision = calculateSamplingDecision(10, 1, "scene_aware", [2.25, 7.75], {
+    endSeconds: 8,
+    startSeconds: 2,
+  });
+
+  assert.deepEqual(decision.timestamps, [5]);
+  assert.equal(decision.policyEffective, "uniform");
+  assert.deepEqual(decision.focusWindow, { endSeconds: 8, startSeconds: 2 });
+});
+
 test("scene candidates are parsed from showinfo output and malformed values are ignored", () => {
   const output = [
     "[Parsed_showinfo_0 @ 0x1] n:1 pts_time:1.250",

tests/unit/openapi-security-tiers.test.ts

@@ -49,76 +49,6 @@ test("GET /api/openapi/spec documents its conditional management auth contract",
   );
 });
 
-test("POST /api/openapi/try documents its bounded management proxy contract", () => {
-  const operation = paths["/api/openapi/try"]?.post;
-
-  assert.ok(operation, "POST /api/openapi/try must be present in docs/openapi.yaml");
-  assert.deepEqual(operation.security, [{ BearerAuth: [] }, { ManagementSessionAuth: [] }]);
-  assert.match(operation.description ?? "", /same-origin/);
-  assert.match(operation.description ?? "", /When `requireLogin` is disabled/);
-
-  const requestBody = operation.requestBody;
-  const requestSchema = requestBody?.content?.["application/json"]?.schema;
-  assert.equal(requestBody?.required, true);
-  assert.equal(requestSchema?.type, "object");
-  assert.deepEqual(requestSchema?.required, ["path"]);
-  assert.deepEqual(requestSchema?.properties?.method?.enum, [
-    "GET",
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "HEAD",
-    "OPTIONS",
-  ]);
-  assert.equal(requestSchema?.properties?.method?.default, "GET");
-  assert.equal(requestSchema?.properties?.path?.minLength, 1);
-  assert.equal(
-    requestSchema?.properties?.path?.pattern,
-    "^/(?:api/|v1/|v1beta/|a2a|\\.well-known/agent\\.json)"
-  );
-  assert.equal(requestSchema?.properties?.headers?.type, "object");
-  assert.deepEqual(requestSchema?.properties?.headers?.additionalProperties, {
-    type: "string",
-  });
-  assert.deepEqual(requestSchema?.properties?.headers?.default, {});
-  assert.ok("body" in requestSchema.properties);
-
-  const successSchema = operation.responses?.["200"]?.content?.["application/json"]?.schema;
-  assert.equal(successSchema?.type, "object");
-  assert.equal(successSchema?.additionalProperties, false);
-  assert.deepEqual(successSchema?.required, [
-    "status",
-    "statusText",
-    "headers",
-    "body",
-    "latencyMs",
-    "contentType",
-  ]);
-  assert.equal(successSchema?.properties?.status?.type, "integer");
-  assert.equal(successSchema?.properties?.status?.minimum, 0);
-  assert.equal(successSchema?.properties?.statusText?.type, "string");
-  assert.equal(successSchema?.properties?.headers?.type, "object");
-  assert.deepEqual(successSchema?.properties?.headers?.additionalProperties, {
-    type: "string",
-  });
-  assert.match(successSchema?.properties?.body?.description ?? "", /10,000 characters/);
-  assert.equal(successSchema?.properties?.latencyMs?.type, "integer");
-  assert.equal(successSchema?.properties?.latencyMs?.minimum, 0);
-  assert.equal(successSchema?.properties?.contentType?.type, "string");
-
-  const badRequestSchema = operation.responses?.["400"]?.content?.["application/json"]?.schema;
-  assert.equal(badRequestSchema?.oneOf?.length, 2);
-  assert.equal(badRequestSchema?.oneOf?.[0]?.$ref, "#/components/schemas/ValidationErrorResponse");
-  assert.equal(badRequestSchema?.oneOf?.[1]?.properties?.error?.type, "string");
-  assert.equal(
-    operation.responses?.["401"]?.$ref,
-    "#/components/responses/ManagementAuthenticationRequired"
-  );
-  assert.equal(operation.responses?.["403"]?.$ref, "#/components/responses/ManagementInvalidToken");
-  assert.equal(operation.responses?.["503"]?.$ref, "#/components/responses/InternalError");
-});
-
 test("every x-always-protected path matches ALWAYS_PROTECTED_API_PATHS in routeGuard.ts", () => {
   for (const [pathStr, methods] of Object.entries(paths)) {
     if (!methods || typeof methods !== "object") continue;