Make the FTS candidate query single-table with a search projection

AGENTS.md

@@ -146,6 +146,30 @@ Worker-crash recovery (`radis.core`):
 
 Labeling uses the shared core LLM client (`radis.core.utils.llm_client`); its timeout, rate-limit gate, and transient-retry knobs are the global `LLM_REQUEST_TIMEOUT_SECONDS`, `LLM_RATE_LIMIT_*`, and `LLM_TRANSIENT_RETRY_*` settings.
 
+PostgreSQL parallelism (compose-only overrides, not in `example.env` — set in `.env`
+only to override the compose file's default):
+
+- `POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER`: Parallel workers per query node scanning
+  the report index (default `4`, raised from PostgreSQL's own default of `2`)
+- `POSTGRES_MAX_PARALLEL_WORKERS`, `POSTGRES_MAX_WORKER_PROCESSES`: Cluster-wide worker
+  pool sizes (each defaults to `8`, PostgreSQL's own default). Raise together with
+  `POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER` on a larger host
+- `POSTGRES_SHARED_BUFFERS`: PostgreSQL's shared memory buffer (default `128MB`,
+  PostgreSQL's own default)
+- `POSTGRES_MAINTENANCE_WORK_MEM`: memory for VACUUM and index builds (default
+  `64MB`, PostgreSQL's own default). Raise for the migration window on a large
+  embedded archive so the pgsearch 0005 HNSW rebuild assembles its graph in
+  memory (a 1.7M-vector corpus built in 7m36s with `16GB` and 7 workers), and
+  for the manual rebuilds in the admin guide's compaction section
+- `POSTGRES_MAX_PARALLEL_MAINTENANCE_WORKERS`: parallel workers per index build
+  (default `2`, PostgreSQL's own default); also capped by
+  `POSTGRES_MAX_PARALLEL_WORKERS`
+- `POSTGRES_SHM_SIZE_BYTES`: tmpfs size of the container's `/dev/shm` in bytes
+  (default `1073741824` = 1 GiB — a cap, not a reservation; Docker's own 64 MB
+  default is too small for parallel queries). Parallel maintenance
+  pre-allocates its whole `maintenance_work_mem` budget here, so keep it at
+  least as large as `POSTGRES_MAINTENANCE_WORK_MEM`
+
 ## Code Standards
 
 - **Style Guide**: Google Python Style Guide

docker-compose.base.yml

@@ -40,8 +40,33 @@ services:
   postgres:
     image: pgvector/pgvector:pg17@sha256:cf134a767f474095eeba57e0117be8e568e011a63f33fbf252f14c9b760f8e6f
     hostname: postgres.local
+    command:
+      - postgres
+      - -c
+      - max_parallel_workers_per_gather=${POSTGRES_MAX_PARALLEL_WORKERS_PER_GATHER:-4}
+      - -c
+      - max_parallel_workers=${POSTGRES_MAX_PARALLEL_WORKERS:-8}
+      - -c
+      - max_worker_processes=${POSTGRES_MAX_WORKER_PROCESSES:-8}
+      - -c
+      - shared_buffers=${POSTGRES_SHARED_BUFFERS:-128MB}
+      - -c
+      - maintenance_work_mem=${POSTGRES_MAINTENANCE_WORK_MEM:-64MB}
+      - -c
+      - max_parallel_maintenance_workers=${POSTGRES_MAX_PARALLEL_MAINTENANCE_WORKERS:-2}
     volumes:
       - postgres_data:/var/lib/postgresql/data
+      # PostgreSQL's parallel workers exchange data through dynamic shared
+      # memory in /dev/shm, and Docker's default segment is only 64 MB.
+      # Parallel maintenance (index builds, e.g. the HNSW rebuild in pgsearch
+      # migration 0005) pre-allocates its whole maintenance_work_mem budget
+      # there, so size this at least as large as POSTGRES_MAINTENANCE_WORK_MEM.
+      # A tmpfs size is a cap, not a reservation. Bytes, because
+      # `docker stack deploy` rejects unit suffixes here (default: 1 GiB).
+      - type: tmpfs
+        target: /dev/shm
+        tmpfs:
+          size: ${POSTGRES_SHM_SIZE_BYTES:-1073741824}
 
 volumes:
   postgres_data:

docker-compose.dev.yml

@@ -26,6 +26,9 @@ services:
     profiles:
       - never
 
+  # In development `web` runs the migrations the workers below wait for, so
+  # their WAIT_INIT_TIMEOUT must outlast the longest migration too. Dev has no
+  # restart policy, so a timeout leaves the worker containers exited.
   web:
     <<: *default-app
     image: radis_dev-web:latest
@@ -52,7 +55,7 @@ services:
     command: >
       bash -c "
         wait-for-it -s postgres.local:5432 -t ${WAIT_POSTGRES_TIMEOUT:-180} &&
-        wait-for-it -s web.local:8000 -t 300 &&
+        wait-for-it -s web.local:8000 -t ${WAIT_INIT_TIMEOUT:-3600} &&
         ./manage.py sweep_stale_tasks &&
         ./manage.py bg_worker -l debug -q default --autoreload
       "
@@ -63,7 +66,7 @@ services:
     command: >
       bash -c "
         wait-for-it -s postgres.local:5432 -t ${WAIT_POSTGRES_TIMEOUT:-180} &&
-        wait-for-it -s web.local:8000 -t 300 &&
+        wait-for-it -s web.local:8000 -t ${WAIT_INIT_TIMEOUT:-3600} &&
         ./manage.py sweep_stale_tasks &&
         ./manage.py bg_worker -l debug -q llm --autoreload
       "

docker-compose.prod.yml

@@ -18,6 +18,12 @@ services:
   # We can't use those manage commands inside the web container in production because
   # the web service may have multiple replicas. So we make sure to only run them once
   # and wait for it to be finished by the web service containers.
+  #
+  # init opens its ok_server port only after `migrate` finishes, and every
+  # service below waits for that port, so WAIT_INIT_TIMEOUT must stay above the
+  # longest migration a deploy runs -- a data migration over a large archive can
+  # take many minutes, and a timeout aborts the `&&` chain and exits the
+  # container.
   init:
     <<: *default-app
     hostname: init.local
@@ -43,7 +49,7 @@ services:
       - ${WEB_HTTPS_PORT:-443}:443
     command: >
       bash -c "
-        wait-for-it -s init.local:8000 -t 300 &&
+        wait-for-it -s init.local:8000 -t ${WAIT_INIT_TIMEOUT:-3600} &&
         echo 'Starting web server ...' &&
         daphne -b 0.0.0.0 -p 80 \\
           -e ssl:443:privateKey=/etc/web/ssl/key.pem:certKey=/etc/web/ssl/cert.pem \\
@@ -60,7 +66,7 @@ services:
     command: >
       bash -c "
         wait-for-it -s postgres.local:5432 -t ${WAIT_POSTGRES_TIMEOUT:-180} &&
-        wait-for-it -s init.local:8000 -t 300 &&
+        wait-for-it -s init.local:8000 -t ${WAIT_INIT_TIMEOUT:-3600} &&
         ./manage.py sweep_stale_tasks &&
         ./manage.py bg_worker -q default
       "
@@ -72,7 +78,7 @@ services:
     command: >
       bash -c "
         wait-for-it -s postgres.local:5432 -t ${WAIT_POSTGRES_TIMEOUT:-180} &&
-        wait-for-it -s init.local:8000 -t 300 &&
+        wait-for-it -s init.local:8000 -t ${WAIT_INIT_TIMEOUT:-3600} &&
         ./manage.py sweep_stale_tasks &&
         ./manage.py bg_worker -q llm
       "