[diegosouzapw]

⚠️ base-red inherited: #11874 — Docs sync + fabricated-docs (strict): README.md does NOT mention 356 for providers. Pre-existing on release/v3.8.51, not touched by this branch.

Summary

FU-06 (Video Bridge series, parent #9760): server-side orchestration that
lets Video Bridge extract audio from a video and run it through Audio
Bridge STT — the original acceptance the fusion primitive (fuseVideoAndAudio)
never covered, since today it only fuses an already-materialized
audioTranscript a caller supplies.

Scope delivered:

• One download, two extractions. The new orchestration
  (src/lib/guardrails/videoBridgeAudioOrchestration.ts) takes the already
  -downloaded video bytes as input — it has no download path of its own, so
  it structurally cannot re-fetch the video.
• New loopback-only broker operation
  (src/app/api/modality-bridge/video/extract/route.ts, mode=audio query
  flag) extracts bounded mono 16 kHz PCM WAV via array-argument ffmpeg
  (src/lib/guardrails/videoBridgeAudioExtraction.ts, reusing
  probeLocalVideo's existing safe-container/format/dimension checks —
  no parallel validation). Never a shell string (Hard Rule deps: bump qs from 6.14.1 to 6.14.2 #13).
• Shared budgets, not a parallel set of limits. mode=audio runs
  through the exact same route file, the same module-level extractionQueue
  singleton, the same MAX_INPUT_BYTES/BROKER_TIMEOUT_MS, and the same
  deadline/AbortSignal composition the frame path already uses.
• Dual opt-in, enforced before either the broker or the transcription
  boundary is ever touched:
  • Operator: modalityBridgeVideoAudioTranscriptionEnabled (new settings
    key, default false — Hard Rule feat: v0.2.0 — advanced routing services, cost analytics, pricing overhaul #20 spirit).
  • Request: a per-request opt-in the caller passes in.
  • Only operatorOptIn && requestOptIn reaches the STT call; all three
    other permutations return attempted: false and never invoke
    extractAudio/transcribe (asserted directly in tests).
• Reuses the existing Audio Bridge transcription boundary —
  callAudioTranscriptionTimed, a new sibling of callAudioTranscription
  in audioBridgeHelpers.ts sharing one refactored-out HTTP/multipart
  helper (sendAudioTranscriptionRequest) — no new STT client. It requests
  response_format=verbose_json and preserves provider-supplied per-segment
  timestamps (timingPrecision: "exact") when present, falling back to one
  whole-clip observation spanning the extracted audio's duration
  (timingPrecision: "coarse") when the provider ignores it.
• Provenance stays server-owned: the orchestrator mints its own
  FusionObservations (source: "audio") directly from the STT response —
  it never calls normalizeVideoTranscript on untrusted client JSON, so it
  does not depend on (or duplicate) the source-trust work feat(guardrails): enforce video transcript provenance, budgets and reconciliation (FU-05 core) #12009 is doing
  on that function.
• Failures stay partial. Every failure path (PROVIDER_UNAVAILABLE,
  EXTRACTION_FAILED, TRANSCRIPTION_FAILED, TIMEOUT, ABORTED) returns
  track: null instead of throwing — a caller's visual-only fallback always
  has a well-defined result to check.
• Result cache (BridgeCache, same primitive Vision/Audio Bridge
  already use) keyed on the video part's ref + STT model — a repeated
  request for the same video does not re-extract or re-transcribe (no
  repeat paid STT call).

Deliberately deferred — composes with #12009 (FU-05, not yet merged):
wiring this orchestration into videoBridgeHelpers.ts::describeVideoPart's
existing fuseVideoAndAudio call site is not done in this PR. That
exact block is also where #12009 is landing the transcript-contract/
provenance-trust rewrite (normalizeVideoTranscript's trustedSource
option, focus scoping, contributingSources reconciliation, cache v4→v5).
Rather than risk a conflicting rewrite of the same lines from two
directions, this PR ships the orchestration as a complete, independently
tested, composable primitive. The follow-up wiring PR (feeding
orchestrateVideoAudioTranscription's FusionTrack into
describeVideoPart's existing audio branch, tagged
source: "audio-bridge" — the transcript-source value already declared in
VideoTranscriptSource but never produced today) is small once #12009's
seam lands.

Test evidence (RED→GREEN, all mocked at the process/provider boundary)

• tests/unit/guardrails/videoBridgeAudioOrchestration.test.ts (17 tests):
  all 4 opt-in permutations (only "both" transcribes; the other 3 assert
  extractAudio/transcribe were never called), extraction success →
  coarse observation, STT segments → exact timing, unavailable provider
  (extraction never runs), extraction timeout vs. generic extraction
  failure, transcription timeout vs. generic transcription failure, caller
  abort during either step, cache hit skips both the broker and the STT
  call, a different video's cache key stays isolated, and the same
  timeoutMs/signal threading through both steps.
• tests/unit/guardrails/videoBridgeAudioExtraction.test.ts (4 tests):
  bounded WAV extraction reusing the probed duration, propagating the
  shared duration cap, rejecting output over the byte cap, and surfacing
  ffmpeg's own "no audio stream" failure.
• tests/unit/guardrails/audioBridgeHelpers.test.ts (+3 tests): the timed
  boundary requests verbose_json, falls back to no-segments when the
  provider ignores it, and drops malformed provider segments instead of
  trusting them — plus all 7 pre-existing tests still pass unmodified
  (callAudioTranscription's behavior is byte-for-byte unchanged).
• tests/unit/video-bridge-broker.test.ts (+6 tests) /
  tests/unit/video-bridge-route-security.test.ts (all 9 pre-existing
  still pass): audio broker client round-trip, malformed/non-WAV response
  rejection, the audio operation observes the identical
  VideoExtractionQueueError/503+Retry-After contract as frames, the
  module-level singleton queue is referenced by both branches, frame-only
  query params are rejected under mode=audio, and the injected extractor
  receives the shared deadline/byte budget.
• tests/unit/video-bridge-settings.test.ts (+1 test): the operator opt-in
  defaults false and the new Zod schema field accepts/rejects correctly.

173/173 tests green across all touched files (command run):

node --import tsx/esm --test \
  tests/unit/guardrails/audioBridgeHelpers.test.ts tests/unit/guardrails/audioBridge.test.ts \
  tests/unit/guardrails/videoAudioFusion.test.ts tests/unit/guardrails/videoBridge.test.ts \
  tests/unit/guardrails/videoBridgeHelpers.test.ts tests/unit/guardrails/videoBridgeRuntime.test.ts \
  tests/unit/guardrails/videoBridgeTranscriptProvenance.test.ts \
  tests/unit/guardrails/videoBridgeAudioExtraction.test.ts \
  tests/unit/guardrails/videoBridgeAudioOrchestration.test.ts \
  tests/unit/video-bridge-broker.test.ts tests/unit/video-bridge-route-security.test.ts \
  tests/unit/video-bridge-settings.test.ts tests/unit/audio-bridge-settings.test.ts \
  tests/unit/modality-bridge-settings.test.ts tests/unit/audio-transcription-handler.test.ts

No existing assertion was weakened or removed.

Gates run locally (green)

• npm run typecheck:core — exit 0
• npm run typecheck:noimplicit:core — exit 0
• npx eslint --suppressions-location config/quality/eslint-suppressions.json <changed files> — 0 problems
• npm run check:complexity-ratchets — OK (2673/2774 cyclomatic, 1193/1223 cognitive — both improved vs. baseline, no new violations)
• node scripts/check/check-file-size.mjs — OK (both new files well under the 1000-line cap; no frozen file touched)
• node scripts/check/check-test-discovery.mjs — OK
• npm run check:cycles — OK, no cycles

Did not run npm run test:coverage per instructions (heaviest gate; CI runs it).

Pending live validation (cannot be done from this environment)

• Working-set/queue caps measured on VPS 192.168.0.15 — not accessible
  from this environment; the shared queue/byte/deadline budgets are proven
  structurally and via unit tests (identical singleton, identical
  VideoExtractionQueueError capacity contract) but not load-measured live.
• Real ffmpeg audio extraction — all ffmpeg/ffprobe invocations are
  exercised through the injectable VideoCommandRunner in tests (no real
  binary invoked); the array-argument construction is asserted directly,
  but a real multi-format video → WAV round-trip was not run here.
• Real provider STT call with verbose_json — callAudioTranscriptionTimed
  is proven against mocked fetch responses shaped like OpenAI-compatible
  verbose_json output; no live call to a real STT provider was made to
  confirm which providers actually return segments.
• Streaming/non-streaming live request checks (sanitized headers
  preserved, no transcript-text retention) — not wired into the live
  request pipeline in this PR (see "Deliberately deferred" above), so there
  is no live streaming/non-streaming request to check yet; the module
  itself never logs or persists transcript text.
• Both test runners (test:unit + test:vitest) and the full release gate
  set on the exact candidate SHA — not run here; only the focused suites
  above were run locally.

Given the above, this uses Refs #11654, not Closes — VPS-side budget
measurement and live-pipeline wiring remain open follow-up work once
#12009 lands.

Refs #11654