# ResearchOwl — Known Issues & Operational Gotchas

## Brotli / aiohttp incompatibility

Do NOT install any brotli backend (`Brotli`, `brotlicffi`) while on aiohttp 3.14.x.
aiohttp's incremental brotli decompressor is broken and fails intermittently
depending on stream chunking ("Can not decode content-encoding: br" on VALID
streams — the same bytes decompress fine offline; httpx is unaffected).

Extra trap: merely *installing* a backend makes aiohttp advertise `br` in the
default `Accept-Encoding` of every session that doesn't set one explicitly.
On 2026-07-04 a scraper fix installed brotlicffi and inadvertently enabled br
project-wide: Ghost/Cloudflare responded in brotli, the decode blew up AFTER
Ghost had already accepted the POST, and the publish fallback re-published →
duplicate drafts + silently lost SEO notices.

Fix applied (commits `397546a` + `76c927f` + `7d07375`, guard relocated
2026-07-05):
- no brotli backend in requirements.txt (comment there explains why),
- explicit `Accept-Encoding: gzip, deflate` on all Ghost/autofill aiohttp
  sessions and on the scraper HEADERS (`57f341f`),
- duplicate guard INSIDE `GhostPublisher.publish_draft` (covers every caller,
  including `/publish`): if the POST is accepted (2xx) but reading the response
  fails, it recovers the just-created draft via `find_draft_by_title(title,
  since=attempt_start)` instead of raising. The guard only fires after an
  accepted POST — a pre-POST failure (Ollama down, menu fetch, links) never
  triggers it, so a stale same-title draft from a previous run can no longer
  swallow freshly generated content.

Note: with no backend installed there is NO brotli fallback at all — a server
that responds `Content-Encoding: br` without it being advertised (misbehaving
CDN) fails undecodable and that source is lost. Accepted trade-off.

The header value lives in one place: `SAFE_ACCEPT_ENCODING` in `src/config.py`.
Every aiohttp session/request must use it explicitly — never rely on aiohttp's
default Accept-Encoding, which silently grows `br` if a backend appears.

Re-test with disclosure.org before ever re-enabling br (e.g. after an aiohttp
upgrade).

## SQLite WAL mode + read-only mounts

The database runs in WAL mode, so even read-only access needs the `-shm` file
writable, or must open with `sqlite3 "file:...?immutable=1"`. Backups (daily
CronJob `researchowl-db-backup`, 03:00 Europe/Madrid, PVC `researchowl-backups`,
7-day retention) inherit WAL mode: to inspect one from a read-only mount use
`?immutable=1`; to restore, copy it to a writable location first.

## DDG (duckduckgo_search) blocks the event loop

`DDGS()` is synchronous (blocking requests inside). Never call it directly from
async code — always wrap in `loop.run_in_executor()` (see `_ddg_text_sync` /
`_ddg_videos_sync` in `src/scraper/exhaustive.py`). Direct calls froze the
entire Telegram bot during searches until fixed on 2026-07-04 (`8dfd011`).

## Google News RSS is a dead end from this infrastructure

`news.google.com/rss` entry links point to `/rss/articles/CBMi…` redirects that
hit a consent wall from EU IPs, and the inner `AU_yqL` id is only resolvable via
Google's private batchexecute API. Do not retry. The news seed uses Bing News
RSS instead (`ENABLE_NEWS_SEED`, real publisher URL in the `?url=` param of
apiclick.aspx — unwrapped by `_unwrap_news_link`).

## Large sources can OOM-kill the pod

On 2026-07-10 the pod was OOMKilled (memory limit was 1Gi) mid-research: a
batch of 20 concurrent sources hit a 98k-word document plus several large PDFs
at once, and pdfplumber's parse spiked RAM past the limit. The in-memory
research task died with the pod and its session sat in `running` forever.

Mitigations now in place:

- Memory limit raised to 2Gi (`k8s-manifests/researchowl/deployment.yaml`).
- PDFs capped at 15MB (was 50MB), checked both via Content-Length and actual
  body size; pdfplumber runs in `run_in_executor` (it is sync + CPU-heavy and
  also froze the event loop, same class of bug as DDGS) and flushes its page
  cache per page.
- Extracted content is truncated to `max_content_length` (300k chars) before
  hitting `source_contents`.
- On startup the bot marks orphaned `running` sessions as `interrupted`.

If a research still dies, the scraped sources survive in the DB: `/process`
re-chunks and scores them without re-scraping.

## Un shot spec escrito por Haiku falla de dos maneras concretas

Medido el 2026-08-01 generando Shorts de verdad contra sesiones reales (JAL
1628 #153, Bélgica #158). Las dos están mitigadas, pero conviene saber que
existen porque las dos son silenciosas si nadie mira.

**1. Comillas rectas dentro de una cadena JSON.** El modelo escribe
`"quote_a": ""CREDIBLE PEOPLE. THEY TOLD CLEARLY WHAT THEY SAW.""` y la cadena
se cierra en la segunda comilla: el JSON entero deja de parsear. Se repitió en
los tres intentos aunque el prompt lo prohíbe explícitamente y aunque el error
se le devolvía con el fragmento exacto. **No se arregla insistiendo**: lo
arregla `_typographic_inner_quotes()` en `src/generator/shortspec.py`, que
convierte esas comillas en `“ ”` recorriendo el texto con estado de cadena.
Sólo se ejecuta después de un fallo de parseo, así que un JSON correcto no pasa
por ahí. Además es lo que se quiere dibujar: las citas del canal van con
tipográficas.

**2. Se copian cifras del ejemplo del prompt.** El `examples/jal1628.json` que
va en el prompt como referencia de formato es también una fuente de datos muy
tentadora. En la primera eval dorada, tres claims del spec generado venían del
ejemplo y no de las fuentes: `232 FT` (largo de un 747) y `40 YEARS` no
aparecían en NINGUNO de los 126 chunks de la sesión, y `RARELY, IF EVER` estaba
en 1 chunk que no entró en el top-40 que vio el modelo. La sección 5 del prompt
lo dice ahora en mayúsculas ("FORMAT ONLY … a number copied from here is a
fabrication") y eso bajó de 3 a 1.

El ejemplo se queda con cifras reales a propósito — uno sintético enseña peor
la forma —, así que la defensa es estructural: `check_grounding()` contrasta lo
que no encuentra en los chunks **contra el propio ejemplo**, y lo que casa ahí
sale en el informe como `🧪 copiado del EJEMPLO del prompt (fuga, no
invención)`. Son dos diagnósticos y piden dos acciones: una invención hay que
verificarla, una fuga hay que borrarla.

Corolario: **el informe de claims no es decorativo**. Si algún día se manda el
vídeo sin él, se estará publicando lo que el modelo recuerde del ejemplo.

## El comprobador de fundamento sólo mira los chunks que vio el modelo

`check_grounding()` compara contra los mismos ~40 chunks que se metieron en el
prompt, no contra los 126 de la sesión. Es deliberado — la pregunta es "¿lo
sacó de lo que le dimos?" — pero produce falsos positivos cuando el dato existe
en la sesión y no entró en el top-k. Un falso positivo cuesta un vistazo; un
falso negativo cuesta la credibilidad del canal.

## YouTube por API: dos candados que no avisan al configurarlo

Ninguno de los dos da un error al montarlo. Los dos se descubren tarde.

**1. Los vídeos suben restringidos a privado y no se abren desde Studio.** La
documentación de [`videos.insert`](https://developers.google.com/youtube/v3/docs/videos/insert)
lo dice: *"All videos uploaded via the videos.insert endpoint from unverified API
projects created after 28 July 2020 will be restricted to private viewing mode"*.
El candado es del **proyecto de API**, no del vídeo, y se levanta pasando la
auditoría de cumplimiento de Google — no cambiando la visibilidad a mano. Por eso
`YOUTUBE_PRIVACY=public` no publica nada: `UploadedVideo.forced_private` detecta
que YouTube devolvió `private` cuando se pidió otra cosa, y el aviso de Telegram
lo dice en vez de dejar creer que salió.

**2. El refresh token caduca a los 7 días si la pantalla de consentimiento sigue
en "Testing".** Google revoca los tokens de las apps sin publicar, así que el bot
funciona una semana y luego empieza a dar `invalid_grant` sin que nada haya
cambiado. La cura es pasar la pantalla a "In production" (con el aviso de "app no
verificada" al dar permiso, que para un único usuario da igual) y volver a sacar
el token. `_auth_error()` traduce `invalid_grant` a ese texto exacto: es el fallo
que más cuesta adivinar y el que más probable es encontrarse.

Corolario de los dos juntos: `/upload_short` **no publica**, y no es una decisión
de diseño que se pueda revertir tocando una env var. Deja el vídeo en el canal
con los metadatos puestos y devuelve el enlace de Studio.