From d76dabc5b0fe695cd1948fe61cebc0d8569faacf Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 11:51:07 -0700
Subject: [PATCH 01/40] refactor(ingestion): make Java API manifest canonical

Make the resource manifest the sole owner of complete Java API mirror records.
Project it into Java and Bash consumers, reject malformed or incomplete
catalogs, and document the ownership rules for future agents.
---
 AGENTS.md                                     |   3 +
 docs/contracts/code-change.md                 |   3 +-
 docs/ingestion.md                             |  16 +-
 docs/pipeline-commands.md                     |  38 +--
 scripts/fetch_all_docs.sh                     | 128 +++++-----
 scripts/lib/documentation_sources.sh          | 218 ++++++++++++++++++
 .../javachat/cli/DocumentationSetCatalog.java |  34 +--
 .../javachat/config/DocsSourceRegistry.java   |  96 +++++---
 .../config/JavaApiDocumentationManifest.java  | 180 +++++++++++++++
 src/main/resources/docs-sources.properties    |   8 +-
 .../java-api-documentation-sources.manifest   |   4 +
 .../javachat/ExtractorQualityTest.java        |  32 +--
 .../javachat/StandaloneExtractionTest.java    |  31 +--
 .../JavaApiDocumentationSourceParityTest.java |  57 +++++
 .../config/DocsSourceRegistryTest.java        |  37 +++
 .../JavaApiDocumentationManifestTest.java     | 106 +++++++++
 16 files changed, 818 insertions(+), 173 deletions(-)
 create mode 100644 scripts/lib/documentation_sources.sh
 create mode 100644 src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
 create mode 100644 src/main/resources/java-api-documentation-sources.manifest
 create mode 100644 src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
 create mode 100644 src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java
 create mode 100644 src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java

diff --git a/AGENTS.md b/AGENTS.md
index c14abd8d..b0a1731a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,6 +17,7 @@ alwaysApply: true
 - [ZA1a-c] Zero Tolerance Policy (zero assumptions, validation workflow, forbidden practices)
 - [GT1a-l] Git, history safety, hooks/signing, lock files, and clean commits
 - [CC1a-d] Clean Code & DDD (Mandatory)
+- [SS1a-j] Single Semantic Owner and Java API catalog ownership
 - [ID1a-d] Idiomatic Patterns & Defaults
 - [EV1a-f] Secrets and Env Vars (no secrets in properties; OpenAI/Qdrant via .env/env)
 - [RC1a-f] Root Cause Resolution (single implementation, no fallbacks, no shims/workarounds)
@@ -78,6 +79,8 @@ alwaysApply: true
 - [SS1f] **Stop-Work Trigger**: If an implementation requires listing the same governed fields/keys/rules in a second place, stop and redesign before editing.
 - [SS1g] **No Positional-Null Sludge**: Constructor/factory calls with repeated placeholder nulls or low-legibility optional argument trains are prohibited; use named factories/builders, parameter objects, or bind/import the canonical owner.
 - [SS1h] **Whole-List Smell**: If a file "knows the whole list" of a governed concept and it is not the canonical owner, the design is presumed wrong and must be reduced or removed.
+- [SS1i] **Java API Catalog Owner**: Define complete Java API mirror records only in `src/main/resources/java-api-documentation-sources.manifest`; consume that manifest from Java, shell, tests, and documentation.
+- [SS1j] **Java API Catalog Projection**: Never recreate Java API releases, URLs, mirror paths, display names, or fetch parameters in properties, constants, arrays, fixtures, or documentation; verify projections with `--list-java-api-sources` and `JavaApiDocumentationSourceParityTest`.
 
 ## [ID1] Idiomatic Patterns & Defaults
 
diff --git a/docs/contracts/code-change.md b/docs/contracts/code-change.md
index 3d328adf..1a1a5063 100644
--- a/docs/contracts/code-change.md
+++ b/docs/contracts/code-change.md
@@ -6,7 +6,7 @@ description: "Evergreen contract for change decisions (new file vs edit), reposi
 
 # Code Change Policy Contract
 
-See `AGENTS.md` ([FS1a-k], [FS1l], [AR1a-f], [ND1a-c], [CC1a-d], [AB1a-d], [RC1a-f], [CS1a-h]).
+See `AGENTS.md` ([SS1a-j], [FS1a-k], [FS1l], [AR1a-f], [ND1a-c], [CC1a-d], [AB1a-d], [RC1a-f], [CS1a-h]).
 
 ## Non-negotiables (applies to every change)
 
@@ -28,6 +28,7 @@ Use this as a hard rule, not a suggestion.
 | Logic change in stable code | Extract/replace via composition; keep stable code stable ([AB1c], [CC1a]) | Add flags, shims, or “compat” paths to hide uncertainty ([RC1b]) |
 | Touching a large/overloaded file | Extract at least one seam (new type + typed contract) ([FS1f], [FS1b]) | Grow the file further ([FS1f]) |
 | Reuse needed across features | Add a domain value object / explicit port / explicit service with intent-revealing name ([AB1b]) | Add `*Utils/*Helper/*Common/*Base*` grab bags ([FS1e]) |
+| Governed catalog change | Edit its single canonical owner and project it everywhere else ([SS1a-c]) | Restate the inventory in code, scripts, tests, fixtures, or docs ([SS1b], [SS1h]) |
 
 ### When adding a method is allowed
 
diff --git a/docs/ingestion.md b/docs/ingestion.md
index 98b5c6d8..40c1cf76 100644
--- a/docs/ingestion.md
+++ b/docs/ingestion.md
@@ -23,11 +23,9 @@ Fetch all configured sources:
 make fetch-all
 ```
 
-This runs `scripts/fetch_all_docs.sh` (requires `wget`). Source URLs live in:
-
-- `src/main/resources/docs-sources.properties`
-
-See [pipeline-commands.md](pipeline-commands.md#scrape-fetch-html-mirrors) for flags (`--force`, `--include-quick`, `--no-clean`).
+This runs `scripts/fetch_all_docs.sh` (requires `wget`). See the canonical source ownership and edit
+workflow in [pipeline-commands.md](pipeline-commands.md#scrape-fetch-html-mirrors), along with flags
+(`--force`, `--include-quick`, `--no-clean`).
 
 ## Process + upload to Qdrant
 
@@ -46,14 +44,14 @@ This runs `scripts/process_all_to_qdrant.sh`, which:
 
 ### Doc set filtering (CLI)
 
-Limit ingestion to specific doc sets:
+List canonical complete Java API paths, then limit ingestion to a selected doc set:
 
 ```bash
-DOCS_SETS=java25-complete make process-doc-sets
-./scripts/process_all_to_qdrant.sh --doc-sets=java25-complete,spring-boot-complete
+./scripts/fetch_all_docs.sh --list-java-api-sources
+DOCS_SETS=relative/path/from/listing make process-doc-sets
 ```
 
-See [pipeline-commands.md](pipeline-commands.md#doc-set-filtering) for the full doc set ID table.
+See [pipeline-commands.md](pipeline-commands.md#doc-set-filtering) for filtering and the canonical Java API listing command.
 
 ## Hybrid vector storage
 
diff --git a/docs/pipeline-commands.md b/docs/pipeline-commands.md
index 72e493ef..3cd197cb 100644
--- a/docs/pipeline-commands.md
+++ b/docs/pipeline-commands.md
@@ -14,7 +14,7 @@ Incremental runs are the default — unchanged content is skipped via SHA-256 ha
 | **Scrape** (mirror HTML) | `make fetch-all` | `make fetch-force` |
 | **Ingest** (chunk → embed → upload) | `make process-all` | Clear state, then `make process-all` ([details](#full-re-ingest)) |
 | **Both** | `make full-pipeline` | `make fetch-force`, then clear state, then `make process-all` |
-| **Ingest subset** | `DOCS_SETS=java25-complete make process-doc-sets` | — |
+| **Ingest subset** | Set `DOCS_SETS` to a catalog path, then run `make process-doc-sets` | — |
 | **Ingest GitHub repo** | `REPO_URL=https://github.com/owner/repo make process-github-repo` | — |
 
 ---
@@ -22,7 +22,19 @@ Incremental runs are the default — unchanged content is skipped via SHA-256 ha
 ## Scrape (fetch HTML mirrors)
 
 The scrape phase mirrors upstream documentation into `data/docs/` using `wget`.
-Source URLs are defined in `src/main/resources/docs-sources.properties`.
+
+### Java API source catalog
+
+Complete Java API mirror records are defined in
+`src/main/resources/java-api-documentation-sources.manifest`; source URLs outside complete Java API mirrors are defined in
+`src/main/resources/docs-sources.properties`.
+
+The manifest is the single semantic owner of each complete Java API release, remote URL, mirror path,
+display name, and fetch policy. Add, change, or remove a complete Java API source by editing one manifest
+row only. Do not add `JAVA*_API_BASE` properties or environment overrides, and do not duplicate the
+manifest's rows or field values in properties, Java constants, shell arrays, tests, or docs.
+Run `./scripts/fetch_all_docs.sh --list-java-api-sources` to inspect the exact rows consumed by the fetch
+script; the CLI catalog and citation registry project the same rows and parity is enforced by tests.
 
 ### Make targets
 
@@ -35,7 +47,7 @@ make fetch-force        # Full: force refetch even if mirrors look complete
 ### Script flags
 
 ```bash
-./scripts/fetch_all_docs.sh [--include-quick] [--no-clean] [--force]
+./scripts/fetch_all_docs.sh [--include-quick] [--no-clean] [--force] [--list-java-api-sources]
 ```
 
 | Flag | Effect |
@@ -43,6 +55,7 @@ make fetch-force        # Full: force refetch even if mirrors look complete
 | `--include-quick` | Also fetch small landing-page mirrors (Spring Boot/Framework/AI quick sets) |
 | `--no-clean` | Do not quarantine incomplete mirrors before refetching |
 | `--force` | Refresh all sources even if they look complete |
+| `--list-java-api-sources` | Print configured Java API source projections without fetching |
 | `--help` | Show usage |
 
 ### What "incremental" means for scraping
@@ -107,23 +120,18 @@ GitHub ingestion runs in headless CLI mode (`spring.main.web-application-type=no
 Limit ingestion to specific doc sets by ID or path:
 
 ```bash
-# Single doc set
-DOCS_SETS=java25-complete make process-doc-sets
-./scripts/process_all_to_qdrant.sh --doc-sets=java25-complete
-
-# Multiple doc sets
-./scripts/process_all_to_qdrant.sh --doc-sets=java25-complete,spring-boot-complete
+# Complete Java API paths: copy relativeMirrorPath from the listing command
+./scripts/fetch_all_docs.sh --list-java-api-sources
+DOCS_SETS=relative/path/from/listing make process-doc-sets
 
-# Path-style IDs
-./scripts/process_all_to_qdrant.sh --doc-sets=java/java25-complete
+# Non-Java example
+./scripts/process_all_to_qdrant.sh --doc-sets=spring-boot-complete
 ```
 
-Available doc set IDs are defined in `DocumentationSetCatalog.java`. Common ones:
+Complete Java API doc set paths are projected from the manifest. Common non-Java doc sets are:
 
 | ID | Content |
 |---|---|
-| `java24-complete` | Java 24 complete API (Oracle Javadoc) |
-| `java25-complete` | Java 25 complete API (Oracle Javadoc) |
 | `spring-boot-complete` | Spring Boot reference + API docs |
 | `spring-framework-complete` | Spring Framework reference + Javadoc |
 | `spring-ai-complete` | Spring AI reference + API (stable + 2.0) |
@@ -230,7 +238,7 @@ To run the CLI directly:
 app_jar=$(ls -1 build/libs/*.jar | grep -v -- "-plain.jar" | head -1)
 
 # With doc set filtering
-DOCS_SETS=java25-complete java -Dspring.profiles.active=cli -jar "$app_jar"
+DOCS_SETS=spring-boot-complete java -Dspring.profiles.active=cli -jar "$app_jar"
 ```
 
 The docs root defaults to `data/docs` unless `DOCS_DIR` is set.
diff --git a/scripts/fetch_all_docs.sh b/scripts/fetch_all_docs.sh
index 12fd7ad6..e045c636 100755
--- a/scripts/fetch_all_docs.sh
+++ b/scripts/fetch_all_docs.sh
@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Consolidated Documentation Fetcher with Deduplication
-# This script fetches all required documentation (Java 24/25, Spring ecosystem)
+# This script fetches all required documentation (configured Java APIs, Spring ecosystem)
 # and ensures no redundant downloads by checking existing files
 
 set -euo pipefail
@@ -12,9 +12,12 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib/shell_bootstrap.sh"
 # shellcheck source=lib/env_loader.sh
 source "$SCRIPT_DIR/lib/env_loader.sh"
+# shellcheck source=lib/documentation_sources.sh
+source "$SCRIPT_DIR/lib/documentation_sources.sh"
 
-# Centralized source URLs (single source of truth)
+# Centralized source definitions
 RES_PROPS="$SCRIPT_DIR/../src/main/resources/docs-sources.properties"
+JAVA_API_SOURCES_MANIFEST="$SCRIPT_DIR/../src/main/resources/java-api-documentation-sources.manifest"
 if [ -f "$RES_PROPS" ]; then
   preserve_process_env_then_source_file "$RES_PROPS"
 fi
@@ -25,6 +28,7 @@ LOG_FILE="$SCRIPT_DIR/../fetch_all_docs.log"
 INCLUDE_QUICK="${INCLUDE_QUICK:-false}"
 CLEAN_INCOMPLETE="${CLEAN_INCOMPLETE:-true}"
 FORCE_REFRESH="${FORCE_REFRESH:-false}"
+LIST_JAVA_API_SOURCES="false"
 for arg in "$@"; do
     case $arg in
         --include-quick)
@@ -36,11 +40,15 @@ for arg in "$@"; do
         --force)
             FORCE_REFRESH="true"
             ;;
+        --list-java-api-sources)
+            LIST_JAVA_API_SOURCES="true"
+            ;;
         --help|-h)
-            echo "Usage: $0 [--include-quick] [--no-clean] [--force]"
+            echo "Usage: $0 [--include-quick] [--no-clean] [--force] [--list-java-api-sources]"
             echo "  --include-quick : Also refresh small 'quick' doc mirrors"
             echo "  --no-clean      : Do not quarantine incomplete mirrors before refetch"
             echo "  --force         : Refresh even when mirrors look complete"
+            echo "  --list-java-api-sources : Print canonical Java API source projections without fetching"
             exit 0
             ;;
         *)
@@ -51,16 +59,6 @@ for arg in "$@"; do
     esac
 done
 
-echo "=============================================="
-echo "Consolidated Documentation Fetcher"
-echo "=============================================="
-echo "Docs root: $DOCS_ROOT"
-echo "Log file: $LOG_FILE"
-echo ""
-
-# Initialize log
-echo "[$(date)] Starting consolidated documentation fetch" > "$LOG_FILE"
-
 extract_meta_version() {
     local file_path="$1"
     if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
@@ -76,30 +74,6 @@ extract_meta_version() {
     echo "$line" | sed -E 's/.*content="([^"]+)".*/\1/'
 }
 
-extract_javadoc_comment_version() {
-    local file_path="$1"
-    if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
-        echo ""
-        return 0
-    fi
-    local line
-    line="$(grep -E '<!-- Generated by javadoc \\([0-9]+' "$file_path" 2>/dev/null | head -n 1 || true)"
-    if [ -z "$line" ]; then
-        echo ""
-        return 0
-    fi
-    echo "$line" | sed -E 's/.*javadoc \\(([0-9]+)\\).*/\\1/'
-}
-
-count_html_files() {
-    local dir="$1"
-    if [ -d "$dir" ]; then
-        find "$dir" -name "*.html" 2>/dev/null | wc -l | tr -d ' '
-    else
-        echo "0"
-    fi
-}
-
 quarantine_incomplete_dir() {
     local dir="$1"
     local name="$2"
@@ -186,13 +160,11 @@ quarantine_versioned_reference_subdirs() {
 #   $2 - target directory (for HTML count)
 #   $3 - human-readable name
 #   $4 - minimum required HTML files (0 = no minimum)
-#   $5 - "true" to allow partial mirrors without failing
 validate_fetch_result() {
     local wget_exit_code="$1"
     local target_dir="$2"
     local name="$3"
     local min_files="$4"
-    local allow_partial="${5:-false}"
 
     local fetched_html_count
     fetched_html_count="$(count_html_files "$target_dir")"
@@ -206,12 +178,8 @@ validate_fetch_result() {
 
     log "${GREEN}✓ $name fetched successfully: $fetched_html_count HTML files${NC}"
     if [ "$min_files" -gt 0 ] && [ "$fetched_html_count" -lt "$min_files" ]; then
-        if [ "$allow_partial" = "true" ]; then
-            log "${YELLOW}⚠ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+); keeping partial mirror for incremental reruns${NC}"
-        else
-            log "${RED}✗ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+)${NC}"
-            return 1
-        fi
+        log "${RED}✗ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+)${NC}"
+        return 1
     fi
     return 0
 }
@@ -220,19 +188,17 @@ validate_fetch_result() {
 # search indices.  This avoids incomplete recursive crawls that miss pages.
 #
 # Arguments:
-#   $1 - base URL (e.g., https://docs.oracle.com/en/java/javase/24/docs/api/)
+#   $1 - Oracle Javadoc base URL
 #   $2 - target directory
 #   $3 - human-readable name
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
-#   $6 - "true" to allow partial mirrors
 fetch_oracle_javadoc_seed() {
     local url="$1"
     local target_dir="$2"
     local name="$3"
     local cut_dirs="$4"
     local min_files="$5"
-    local allow_partial="${6:-false}"
 
     local seed_file="$target_dir/.oracle-javadoc-seed.txt"
     log "${BLUE}ℹ Oracle Javadoc detected; generating explicit URL seed list...${NC}"
@@ -263,7 +229,7 @@ fetch_oracle_javadoc_seed() {
     local wget_exit_code=$?
     cd - > /dev/null
 
-    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files" "$allow_partial"
+    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files"
 }
 
 # Fetches documentation using wget --mirror for generic (non-Oracle) sites.
@@ -275,7 +241,6 @@ fetch_oracle_javadoc_seed() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
-#   $7 - "true" to allow partial mirrors (optional)
 fetch_docs_mirror() {
     local url="$1"
     local target_dir="$2"
@@ -283,7 +248,6 @@ fetch_docs_mirror() {
     local cut_dirs="$4"
     local min_files="$5"
     local reject_regex="${6:-}"
-    local allow_partial="${7:-false}"
 
     local wget_args=(
         --mirror \
@@ -316,7 +280,7 @@ fetch_docs_mirror() {
     local wget_exit_code=$?
     cd - > /dev/null
 
-    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files" "$allow_partial"
+    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files"
 }
 
 # Dispatches documentation fetching: performs pre-fetch housekeeping (existing
@@ -330,7 +294,6 @@ fetch_docs_mirror() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
-#   $7 - "true" to allow partial mirrors (optional)
 fetch_docs() {
     local url="$1"
     local target_dir="$2"
@@ -338,7 +301,6 @@ fetch_docs() {
     local cut_dirs="$4"
     local min_files="$5"
     local reject_regex="${6:-}"
-    local allow_partial="${7:-false}"
 
     # Allow config-friendly placeholder for regex alternation without breaking our field delimiter.
     reject_regex="${reject_regex//__OR__/|}"
@@ -349,7 +311,7 @@ fetch_docs() {
     if [ "$existing_count" -gt 0 ]; then
         log "${BLUE}ℹ Existing mirror: $existing_count HTML files${NC}"
     fi
-    if [ "$allow_partial" != "true" ] && [ "$min_files" -gt 0 ] && [ "$existing_count" -gt 0 ] && [ "$existing_count" -lt "$min_files" ]; then
+    if [ "$min_files" -gt 0 ] && [ "$existing_count" -gt 0 ] && [ "$existing_count" -lt "$min_files" ]; then
         quarantine_incomplete_dir "$target_dir" "$name" "$existing_count" "$min_files"
     fi
 
@@ -374,14 +336,14 @@ fetch_docs() {
             log "${GREEN}✓ $name already fetched: $existing_count HTML files (minimum: $min_files)${NC}"
             return 0
         fi
-        fetch_oracle_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$allow_partial"
+        fetch_oracle_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files"
     else
-        fetch_docs_mirror "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex" "$allow_partial"
+        fetch_docs_mirror "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex"
     fi
 }
 
 # Documentation sources configuration
-# Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX|ALLOW_PARTIAL
+# Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX
 DOC_SOURCES=(
     # Spring Boot (current)
     "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot-complete|Spring Boot Reference (current)|1|50|"
@@ -403,11 +365,16 @@ DOC_SOURCES=(
     "${JAVA25_RELEASE_NOTES_ISSUES_URL:-https://www.oracle.com/java/technologies/javase/25-relnote-issues.html}|$DOCS_ROOT/oracle/javase|Java 25 Release Notes Issues|3|1|"
     "${IBM_JAVA25_ARTICLE_URL:-https://developer.ibm.com/articles/java-whats-new-java25/}|$DOCS_ROOT/ibm/articles|IBM Java 25 Overview|1|1|"
     "${JETBRAINS_JAVA25_BLOG_URL:-https://blog.jetbrains.com/idea/2025/09/java-25-lts-and-intellij-idea/}|$DOCS_ROOT/jetbrains/idea/2025/09|JetBrains Java 25 Blog|3|1|"
-
-    "${JAVA24_API_BASE:-https://docs.oracle.com/en/java/javase/24/docs/api/}|$DOCS_ROOT/java/java24-complete|Java 24 Complete API|5|9000||true"
-    "${JAVA25_API_BASE:-https://docs.oracle.com/en/java/javase/25/docs/api/}|$DOCS_ROOT/java/java25-complete|Java 25 Documentation|5|9000||true"
 )
 
+load_java_api_documentation_sources "$JAVA_API_SOURCES_MANIFEST"
+append_java_api_fetch_sources "$DOCS_ROOT"
+
+if [ "$LIST_JAVA_API_SOURCES" = "true" ]; then
+    printf '%s\n' "${JAVA_API_SOURCE_PROJECTIONS[@]}"
+    exit 0
+fi
+
 if [ "$INCLUDE_QUICK" = "true" ]; then
     DOC_SOURCES+=(
         "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot|Spring Boot Quick (reference landing)|1|1|"
@@ -417,6 +384,16 @@ if [ "$INCLUDE_QUICK" = "true" ]; then
     )
 fi
 
+echo "=============================================="
+echo "Consolidated Documentation Fetcher"
+echo "=============================================="
+echo "Docs root: $DOCS_ROOT"
+echo "Log file: $LOG_FILE"
+echo ""
+
+# Initialize log
+echo "[$(date)] Starting consolidated documentation fetch" > "$LOG_FILE"
+
 # Statistics
 TOTAL_FETCHED=0
 TOTAL_FAILED=0
@@ -427,18 +404,18 @@ echo "=============================================="
 
 # Process each documentation source
 for source in "${DOC_SOURCES[@]}"; do
-    IFS='|' read -r url target_dir name cut_dirs min_files reject_regex allow_partial <<< "$source"
+    IFS='|' read -r url target_dir name cut_dirs min_files reject_regex <<< "$source"
     
     echo ""
     log "Processing: $name"
     log "URL: $url"
     log "Target: $target_dir"
     
-    if fetch_docs "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "${reject_regex:-}" "${allow_partial:-false}"; then
-        ((TOTAL_FETCHED++))
+    if fetch_docs "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "${reject_regex:-}"; then
+        TOTAL_FETCHED=$((TOTAL_FETCHED + 1))
     else
-        ((TOTAL_FAILED++))
-        log "${YELLOW}Warning: Failed to fetch $name, continuing with others...${NC}"
+        TOTAL_FAILED=$((TOTAL_FAILED + 1))
+        log "${RED}Error: Failed to fetch $name; auditing the remaining sources before exit${NC}"
     fi
 done
 
@@ -460,15 +437,19 @@ SPRING_BOOT_REFERENCE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-boot-co
 SPRING_FRAMEWORK_REFERENCE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-framework-complete/reference/index.html")"
 SPRING_AI_REFERENCE_STABLE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference/reference/index.html")"
 SPRING_AI_REFERENCE_2_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference-2/reference/2.0/index.html")"
-JAVA24_JAVADOC_VERSION="$(extract_javadoc_comment_version "$DOCS_ROOT/java/java24-complete/api/index.html")"
-JAVA25_JAVADOC_VERSION="$(extract_javadoc_comment_version "$DOCS_ROOT/java/java25-complete/api/index.html")"
+JAVA_JAVADOC_VERSIONS_METADATA="$(render_java_javadoc_versions_metadata "$DOCS_ROOT")"
+JAVA_COMPLETE_DIRECTORIES_METADATA="$(render_java_complete_directories_metadata "$DOCS_ROOT")"
 
 log "  - Total HTML files: $TOTAL_HTML"
 log "  - Total files: $TOTAL_FILES"
 log "  - Documentation root: $DOCS_ROOT"
 
 echo ""
-log "${GREEN}✅ Documentation fetch complete!${NC}"
+if [ "$TOTAL_FAILED" -eq 0 ]; then
+    log "${GREEN}✅ Documentation fetch complete!${NC}"
+else
+    log "${RED}✗ Documentation fetch failed for $TOTAL_FAILED source(s)${NC}"
+fi
 log "Check log for details: $LOG_FILE"
 
 # Create a marker file with fetch metadata
@@ -483,16 +464,14 @@ cat > "$METADATA_FILE" << EOF
     "total_files": $TOTAL_FILES
   },
   "versions": {
-    "java24_javadoc": "$JAVA24_JAVADOC_VERSION",
-    "java25_javadoc": "$JAVA25_JAVADOC_VERSION",
+$JAVA_JAVADOC_VERSIONS_METADATA,
     "spring_boot_reference": "$SPRING_BOOT_REFERENCE_VERSION",
     "spring_framework_reference": "$SPRING_FRAMEWORK_REFERENCE_VERSION",
     "spring_ai_reference_stable": "$SPRING_AI_REFERENCE_STABLE_VERSION",
     "spring_ai_reference_2": "$SPRING_AI_REFERENCE_2_VERSION"
   },
   "directories": {
-    "java24_complete": "$(find "$DOCS_ROOT/java/java24-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "java25_complete": "$(find "$DOCS_ROOT/java/java25-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+$JAVA_COMPLETE_DIRECTORIES_METADATA,
     "spring_boot_complete": "$(find "$DOCS_ROOT/spring-boot-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
     "spring_framework_complete": "$(find "$DOCS_ROOT/spring-framework-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
     "spring_ai_reference_stable": "$(find "$DOCS_ROOT/spring-ai-reference" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
@@ -505,4 +484,7 @@ EOF
 
 log "Metadata saved to: $METADATA_FILE"
 echo ""
+if [ "$TOTAL_FAILED" -gt 0 ]; then
+    exit 1
+fi
 echo "Next step: Run 'make run' or './scripts/process_all_to_qdrant.sh' to process and upload to Qdrant"
diff --git a/scripts/lib/documentation_sources.sh b/scripts/lib/documentation_sources.sh
new file mode 100644
index 00000000..a0ed3d02
--- /dev/null
+++ b/scripts/lib/documentation_sources.sh
@@ -0,0 +1,218 @@
+#!/bin/bash
+
+JAVA_API_SOURCE_MANIFEST_HEADER='javaRelease|remoteBaseUrl|relativeMirrorPath|displayName|cutDirectories|minimumHtmlFiles|rejectRegex|allowPartial'
+JAVA_API_SOURCE_MAX_INTEGER='2147483647'
+JAVA_API_SOURCE_PROJECTIONS=()
+
+is_canonical_manifest_integer() {
+    local integer_text="$1"
+    if [[ ! "$integer_text" =~ ^(0|[1-9][0-9]*)$ ]]; then
+        return 1
+    fi
+    if [ "${#integer_text}" -gt "${#JAVA_API_SOURCE_MAX_INTEGER}" ]; then
+        return 1
+    fi
+    if [ "${#integer_text}" -eq "${#JAVA_API_SOURCE_MAX_INTEGER}" ] \
+        && [ "$integer_text" -gt "$JAVA_API_SOURCE_MAX_INTEGER" ]; then
+        return 1
+    fi
+}
+
+has_boundary_whitespace() {
+    local manifest_text="$1"
+    local LC_ALL=C
+    [[ "$manifest_text" =~ ^[[:space:]] || "$manifest_text" =~ [[:space:]]$ ]]
+}
+
+is_blank_manifest_line() {
+    local manifest_line="$1"
+    local LC_ALL=C
+    [[ "$manifest_line" =~ ^[[:space:]]*$ ]]
+}
+
+count_html_files() {
+    local directory_path="$1"
+    if [ -d "$directory_path" ]; then
+        find "$directory_path" -name "*.html" 2>/dev/null | wc -l | tr -d ' '
+    else
+        echo "0"
+    fi
+}
+
+extract_javadoc_comment_version() {
+    local file_path="$1"
+    if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
+        echo ""
+        return 0
+    fi
+    local line
+    line="$(grep -E '<!-- Generated by javadoc \\([0-9]+' "$file_path" 2>/dev/null | head -n 1 || true)"
+    if [ -z "$line" ]; then
+        echo ""
+        return 0
+    fi
+    echo "$line" | sed -E 's/.*javadoc \\(([0-9]+)\\).*/\\1/'
+}
+
+load_java_api_documentation_sources() {
+    local source_manifest_file="$1"
+    if [ ! -f "$source_manifest_file" ]; then
+        echo "Java API source manifest not found: $source_manifest_file" >&2
+        return 1
+    fi
+
+    JAVA_API_SOURCE_PROJECTIONS=()
+    local manifest_header=""
+    local expected_delimiter_count=-1
+    local manifest_line_number=0
+    local manifest_line
+    local retained_java_releases=("")
+    local retained_relative_mirror_paths=("")
+    while IFS= read -r manifest_line || [ -n "$manifest_line" ]; do
+        manifest_line_number=$((manifest_line_number + 1))
+        if [ "$manifest_line_number" -eq 1 ]; then
+            manifest_header="$manifest_line"
+            if [ -z "$manifest_header" ]; then
+                echo "Java API source manifest header cannot be blank: $source_manifest_file" >&2
+                return 1
+            fi
+            if [ "$manifest_header" != "$JAVA_API_SOURCE_MANIFEST_HEADER" ]; then
+                echo "Java API source manifest header is invalid: $source_manifest_file" >&2
+                return 1
+            fi
+            local header_delimiters="${manifest_header//[^|]/}"
+            expected_delimiter_count=${#header_delimiters}
+            continue
+        fi
+        if is_blank_manifest_line "$manifest_line"; then
+            echo "Java API source manifest line $manifest_line_number cannot be blank" >&2
+            return 1
+        fi
+
+        local source_delimiters="${manifest_line//[^|]/}"
+        if [ "${#source_delimiters}" -ne "$expected_delimiter_count" ]; then
+            echo "Java API source manifest line $manifest_line_number has an invalid column count" >&2
+            return 1
+        fi
+
+        local javaRelease
+        local remoteBaseUrl
+        local relativeMirrorPath
+        local displayName
+        local cutDirectories
+        local minimumHtmlFiles
+        local rejectRegex
+        local allowPartial
+        IFS='|' read -r javaRelease remoteBaseUrl relativeMirrorPath displayName cutDirectories minimumHtmlFiles rejectRegex allowPartial <<< "$manifest_line"
+
+        if ! is_canonical_manifest_integer "$javaRelease" || [ "$javaRelease" = "0" ]; then
+            echo "Java API source manifest line $manifest_line_number has an invalid Java release" >&2
+            return 1
+        fi
+        if [ -z "$remoteBaseUrl" ] || [ -z "$relativeMirrorPath" ] || [ -z "$displayName" ] \
+            || has_boundary_whitespace "$remoteBaseUrl" \
+            || has_boundary_whitespace "$relativeMirrorPath" \
+            || has_boundary_whitespace "$displayName"; then
+            echo "Java API source manifest line $manifest_line_number has a blank required field" >&2
+            return 1
+        fi
+        if ! is_canonical_manifest_integer "$cutDirectories"; then
+            echo "Java API source manifest line $manifest_line_number has invalid cut directories" >&2
+            return 1
+        fi
+        if ! is_canonical_manifest_integer "$minimumHtmlFiles" || [ "$minimumHtmlFiles" = "0" ]; then
+            echo "Java API source manifest line $manifest_line_number has invalid minimum HTML files" >&2
+            return 1
+        fi
+        if [ "$allowPartial" != "true" ] && [ "$allowPartial" != "false" ]; then
+            echo "Java API source manifest line $manifest_line_number has invalid allow-partial semantics" >&2
+            return 1
+        fi
+        local retained_java_release
+        for retained_java_release in "${retained_java_releases[@]}"; do
+            if [ "$retained_java_release" = "$javaRelease" ]; then
+                echo "Java API source manifest line $manifest_line_number duplicates Java release $javaRelease" >&2
+                return 1
+            fi
+        done
+        local retained_relative_mirror_path
+        for retained_relative_mirror_path in "${retained_relative_mirror_paths[@]}"; do
+            if [ "$retained_relative_mirror_path" = "$relativeMirrorPath" ]; then
+                echo "Java API source manifest line $manifest_line_number duplicates mirror path $relativeMirrorPath" >&2
+                return 1
+            fi
+        done
+
+        retained_java_releases+=("$javaRelease")
+        retained_relative_mirror_paths+=("$relativeMirrorPath")
+        JAVA_API_SOURCE_PROJECTIONS+=("$manifest_line")
+    done < "$source_manifest_file"
+
+    if [ -z "$manifest_header" ]; then
+        echo "Java API source manifest is empty: $source_manifest_file" >&2
+        return 1
+    fi
+    if [ "${#JAVA_API_SOURCE_PROJECTIONS[@]}" -eq 0 ]; then
+        echo "No canonical Java API sources found in $source_manifest_file" >&2
+        return 1
+    fi
+}
+
+append_java_api_fetch_sources() {
+    local docs_root="$1"
+    local java_api_source_projection
+    for java_api_source_projection in "${JAVA_API_SOURCE_PROJECTIONS[@]}"; do
+        local javaRelease
+        local remoteBaseUrl
+        local relativeMirrorPath
+        local displayName
+        local cutDirectories
+        local minimumHtmlFiles
+        local rejectRegex
+        local allowPartial
+        IFS='|' read -r javaRelease remoteBaseUrl relativeMirrorPath displayName cutDirectories minimumHtmlFiles rejectRegex allowPartial <<< "$java_api_source_projection"
+        DOC_SOURCES+=("$remoteBaseUrl|$docs_root/$relativeMirrorPath|$displayName|$cutDirectories|$minimumHtmlFiles|$rejectRegex|$allowPartial")
+    done
+}
+
+render_java_javadoc_versions_metadata() {
+    local docs_root="$1"
+    local metadata_separator=""
+    local java_api_source_projection
+    for java_api_source_projection in "${JAVA_API_SOURCE_PROJECTIONS[@]}"; do
+        local javaRelease
+        local remoteBaseUrl
+        local relativeMirrorPath
+        local displayName
+        local cutDirectories
+        local minimumHtmlFiles
+        local rejectRegex
+        local allowPartial
+        IFS='|' read -r javaRelease remoteBaseUrl relativeMirrorPath displayName cutDirectories minimumHtmlFiles rejectRegex allowPartial <<< "$java_api_source_projection"
+        local javadoc_version
+        javadoc_version="$(extract_javadoc_comment_version "$docs_root/$relativeMirrorPath/api/index.html")"
+        printf '%s    "java%s_javadoc": "%s"' "$metadata_separator" "$javaRelease" "$javadoc_version"
+        metadata_separator=$',\n'
+    done
+}
+
+render_java_complete_directories_metadata() {
+    local docs_root="$1"
+    local metadata_separator=""
+    local java_api_source_projection
+    for java_api_source_projection in "${JAVA_API_SOURCE_PROJECTIONS[@]}"; do
+        local javaRelease
+        local remoteBaseUrl
+        local relativeMirrorPath
+        local displayName
+        local cutDirectories
+        local minimumHtmlFiles
+        local rejectRegex
+        local allowPartial
+        IFS='|' read -r javaRelease remoteBaseUrl relativeMirrorPath displayName cutDirectories minimumHtmlFiles rejectRegex allowPartial <<< "$java_api_source_projection"
+        local html_file_count
+        html_file_count="$(count_html_files "$docs_root/$relativeMirrorPath")"
+        printf '%s    "java%s_complete": "%s"' "$metadata_separator" "$javaRelease" "$html_file_count"
+        metadata_separator=$',\n'
+    done
+}
diff --git a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
index 3bd0cd12..e3379bc9 100644
--- a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
+++ b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
@@ -1,5 +1,7 @@
 package com.williamcallahan.javachat.cli;
 
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -12,10 +14,6 @@ final class DocumentationSetCatalog {
 
     private static final String DOCSET_PDF_BOOKS_NAME = "PDF Books";
     private static final String DOCSET_PDF_BOOKS_PATH = "books";
-    private static final String DOCSET_JAVA_24_COMPLETE_NAME = "Java 24 Complete API";
-    private static final String DOCSET_JAVA_24_COMPLETE_PATH = "java/java24-complete";
-    private static final String DOCSET_JAVA_25_COMPLETE_NAME = "Java 25 Documentation";
-    private static final String DOCSET_JAVA_25_COMPLETE_PATH = "java/java25-complete";
     private static final String DOCSET_JAVA_25_RELEASE_NOTES_NAME = "Java 25 Release Notes Issues";
     private static final String DOCSET_JAVA_25_RELEASE_NOTES_PATH = "oracle/javase";
     private static final String DOCSET_IBM_JAVA_25_ARTICLE_NAME = "IBM Java 25 Overview";
@@ -40,16 +38,7 @@ final class DocumentationSetCatalog {
     private static final String DOCSET_SPRING_AI_QUICK_NAME = "Spring AI Quick";
     private static final String DOCSET_SPRING_AI_QUICK_PATH = "spring-ai";
 
-    private static final List<DocumentationSet> BASE_DOCUMENTATION_SETS = List.of(
-            new DocumentationSet(DOCSET_PDF_BOOKS_NAME, DOCSET_PDF_BOOKS_PATH),
-            new DocumentationSet(DOCSET_JAVA_24_COMPLETE_NAME, DOCSET_JAVA_24_COMPLETE_PATH),
-            new DocumentationSet(DOCSET_JAVA_25_COMPLETE_NAME, DOCSET_JAVA_25_COMPLETE_PATH),
-            new DocumentationSet(DOCSET_JAVA_25_RELEASE_NOTES_NAME, DOCSET_JAVA_25_RELEASE_NOTES_PATH),
-            new DocumentationSet(DOCSET_IBM_JAVA_25_ARTICLE_NAME, DOCSET_IBM_JAVA_25_ARTICLE_PATH),
-            new DocumentationSet(DOCSET_JETBRAINS_JAVA_25_BLOG_NAME, DOCSET_JETBRAINS_JAVA_25_BLOG_PATH),
-            new DocumentationSet(DOCSET_SPRING_BOOT_COMPLETE_NAME, DOCSET_SPRING_BOOT_COMPLETE_PATH),
-            new DocumentationSet(DOCSET_SPRING_FRAMEWORK_COMPLETE_NAME, DOCSET_SPRING_FRAMEWORK_COMPLETE_PATH),
-            new DocumentationSet(DOCSET_SPRING_AI_COMPLETE_NAME, DOCSET_SPRING_AI_COMPLETE_PATH));
+    private static final List<DocumentationSet> BASE_DOCUMENTATION_SETS = buildBaseDocumentationSets();
 
     private static final List<DocumentationSet> QUICK_DOCUMENTATION_SETS = List.of(
             new DocumentationSet(DOCSET_JAVA_24_QUICK_NAME, DOCSET_JAVA_24_QUICK_PATH),
@@ -64,6 +53,23 @@ final class DocumentationSetCatalog {
 
     private DocumentationSetCatalog() {}
 
+    private static List<DocumentationSet> buildBaseDocumentationSets() {
+        List<DocumentationSet> baseDocumentationSets = new ArrayList<>();
+        baseDocumentationSets.add(new DocumentationSet(DOCSET_PDF_BOOKS_NAME, DOCSET_PDF_BOOKS_PATH));
+        baseDocumentationSets.addAll(DocsSourceRegistry.javaApiDocumentationSources().stream()
+                .map(javaApiDocumentationSource -> new DocumentationSet(
+                        javaApiDocumentationSource.displayName(), javaApiDocumentationSource.relativeMirrorPath()))
+                .toList());
+        baseDocumentationSets.addAll(List.of(
+                new DocumentationSet(DOCSET_JAVA_25_RELEASE_NOTES_NAME, DOCSET_JAVA_25_RELEASE_NOTES_PATH),
+                new DocumentationSet(DOCSET_IBM_JAVA_25_ARTICLE_NAME, DOCSET_IBM_JAVA_25_ARTICLE_PATH),
+                new DocumentationSet(DOCSET_JETBRAINS_JAVA_25_BLOG_NAME, DOCSET_JETBRAINS_JAVA_25_BLOG_PATH),
+                new DocumentationSet(DOCSET_SPRING_BOOT_COMPLETE_NAME, DOCSET_SPRING_BOOT_COMPLETE_PATH),
+                new DocumentationSet(DOCSET_SPRING_FRAMEWORK_COMPLETE_NAME, DOCSET_SPRING_FRAMEWORK_COMPLETE_PATH),
+                new DocumentationSet(DOCSET_SPRING_AI_COMPLETE_NAME, DOCSET_SPRING_AI_COMPLETE_PATH)));
+        return List.copyOf(baseDocumentationSets);
+    }
+
     static List<DocumentationSet> baseSets() {
         return BASE_DOCUMENTATION_SETS;
     }
diff --git a/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java b/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
index 3512f342..557d9ad2 100644
--- a/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
+++ b/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
@@ -4,6 +4,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.LinkedHashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
@@ -17,8 +18,8 @@
  * Provides a single place to define how locally mirrored paths map back to
  * authoritative remote URLs for citations and ingestion.
  *
- * Source of truth for remote base URLs is src/main/resources/docs-sources.properties.
- * Scripts also source the same file to avoid DRY.
+ * Complete Java API sources are governed by {@code java-api-documentation-sources.manifest};
+ * other remote base URLs are governed by {@code docs-sources.properties}.
  */
 public final class DocsSourceRegistry {
 
@@ -26,13 +27,10 @@ public final class DocsSourceRegistry {
 
     private static final String DOCS_SOURCES_RESOURCE = "/docs-sources.properties";
     private static final String LOG_DOCS_SOURCES_LOADED = "Loaded docs-sources.properties with {} entries";
-    private static final String LOG_DOCS_SOURCES_MISSING =
-            "docs-sources.properties not found on classpath; using default URL mappings";
+    private static final String LOG_DOCS_SOURCES_MISSING = "docs-sources.properties not found on classpath";
     private static final String LOG_DOCS_SOURCES_LOAD_FAILED =
-            "Failed to load docs-sources.properties (exceptionType={}) - using default URL mappings";
+            "Failed to load docs-sources.properties (exceptionType={})";
 
-    private static final String JAVA24_API_BASE_KEY = "JAVA24_API_BASE";
-    private static final String JAVA25_API_BASE_KEY = "JAVA25_API_BASE";
     private static final String ORACLE_JAVASE_BASE_KEY = "ORACLE_JAVASE_BASE";
     private static final String IBM_ARTICLES_BASE_KEY = "IBM_ARTICLES_BASE";
     private static final String JETBRAINS_IDEA_2025_09_BASE_KEY = "JETBRAINS_IDEA_2025_09_BASE";
@@ -47,8 +45,6 @@ public final class DocsSourceRegistry {
 
     private static final String REDACTED_LOCAL_URL = "(local file path redacted)";
 
-    private static final String DEFAULT_JAVA24 = "https://docs.oracle.com/en/java/javase/24/docs/api/";
-    private static final String DEFAULT_JAVA25 = "https://docs.oracle.com/en/java/javase/25/docs/api/";
     private static final String DEFAULT_ORACLE_JAVASE_BASE = "https://www.oracle.com/java/technologies/javase/";
     private static final String DEFAULT_IBM_ARTICLES_BASE = "https://developer.ibm.com/articles/";
     private static final String DEFAULT_JETBRAINS_IDEA_2025_09_BASE = "https://blog.jetbrains.com/idea/2025/09/";
@@ -65,12 +61,6 @@ public final class DocsSourceRegistry {
     private static final String DEFAULT_SPRING_AI_API_2_BASE = "https://docs.spring.io/spring-ai/docs/2.0.x/api/";
 
     private static final String LOCAL_DOCS_ROOT = "/data/docs/";
-    private static final String LOCAL_DOCS_JAVA24 = LOCAL_DOCS_ROOT + "java24/";
-    private static final String LOCAL_DOCS_JAVA24_NESTED = LOCAL_DOCS_ROOT + "java/java24/";
-    private static final String LOCAL_DOCS_JAVA24_COMPLETE = LOCAL_DOCS_ROOT + "java/java24-complete/";
-    private static final String LOCAL_DOCS_JAVA25 = LOCAL_DOCS_ROOT + "java25/";
-    private static final String LOCAL_DOCS_JAVA25_NESTED = LOCAL_DOCS_ROOT + "java/java25/";
-    private static final String LOCAL_DOCS_JAVA25_COMPLETE = LOCAL_DOCS_ROOT + "java/java25-complete/";
     private static final String LOCAL_DOCS_SPRING_BOOT = LOCAL_DOCS_ROOT + "spring-boot/";
     private static final String LOCAL_DOCS_SPRING_BOOT_COMPLETE = LOCAL_DOCS_ROOT + "spring-boot-complete/";
     private static final String LOCAL_DOCS_SPRING_FRAMEWORK = LOCAL_DOCS_ROOT + "spring-framework/";
@@ -95,9 +85,9 @@ public final class DocsSourceRegistry {
     private static final String SPRING_DOCS_HTTPS_PREFIX = HTTPS_PREFIX + SPRING_DOCS_HOST_MARKER;
 
     private static final Properties PROPS = loadDocsSourceProperties();
+    private static final List<JavaApiDocumentationSource> JAVA_API_DOCUMENTATION_SOURCES =
+            JavaApiDocumentationManifest.load();
 
-    public static final String JAVA24_API_BASE = resolveSetting(JAVA24_API_BASE_KEY, DEFAULT_JAVA24);
-    public static final String JAVA25_API_BASE = resolveSetting(JAVA25_API_BASE_KEY, DEFAULT_JAVA25);
     public static final String ORACLE_JAVASE_BASE = resolveSetting(ORACLE_JAVASE_BASE_KEY, DEFAULT_ORACLE_JAVASE_BASE);
     public static final String IBM_ARTICLES_BASE = resolveSetting(IBM_ARTICLES_BASE_KEY, DEFAULT_IBM_ARTICLES_BASE);
     public static final String JETBRAINS_IDEA_2025_09_BASE =
@@ -123,6 +113,64 @@ public final class DocsSourceRegistry {
 
     private DocsSourceRegistry() {}
 
+    /**
+     * Describes one complete Java API mirror projected from the canonical manifest.
+     *
+     * @param javaRelease Java release number used by retrieval provenance
+     * @param remoteBaseUrl authoritative Oracle Javadoc base URL
+     * @param relativeMirrorPath canonical path beneath {@code data/docs}
+     * @param displayName operator-facing ingestion name
+     * @param cutDirectories number of leading remote path segments removed during mirroring
+     * @param minimumHtmlFiles minimum accepted mirror size
+     * @param rejectRegex crawler exclusion expression, or blank when no exclusion applies
+     * @param allowPartial whether the fetcher accepts a validated partial mirror
+     */
+    public record JavaApiDocumentationSource(
+            String javaRelease,
+            String remoteBaseUrl,
+            String relativeMirrorPath,
+            String displayName,
+            int cutDirectories,
+            int minimumHtmlFiles,
+            String rejectRegex,
+            boolean allowPartial) {
+        public JavaApiDocumentationSource {
+            int parsedJavaRelease =
+                    JavaApiDocumentationManifest.requireCanonicalUnsignedInteger(javaRelease, "javaRelease");
+            if (parsedJavaRelease < 1) {
+                throw new IllegalArgumentException("Java release must be positive");
+            }
+            JavaApiDocumentationManifest.requireManifestText(remoteBaseUrl, "remoteBaseUrl", false);
+            JavaApiDocumentationManifest.requireManifestText(relativeMirrorPath, "relativeMirrorPath", false);
+            JavaApiDocumentationManifest.requireManifestText(displayName, "displayName", false);
+            if (cutDirectories < 0) {
+                throw new IllegalArgumentException("Java API cut directories cannot be negative");
+            }
+            if (minimumHtmlFiles < 1) {
+                throw new IllegalArgumentException("Java API minimum HTML files must be positive");
+            }
+            JavaApiDocumentationManifest.requireManifestText(rejectRegex, "rejectRegex", true);
+        }
+
+        /**
+         * Serializes this validated source with the canonical manifest grammar.
+         *
+         * @return exact manifest record row
+         */
+        public String toManifestRow() {
+            return JavaApiDocumentationManifest.serialize(this);
+        }
+    }
+
+    /**
+     * Returns complete Java API sources projected from the canonical manifest.
+     *
+     * @return immutable sources in manifest order
+     */
+    public static List<JavaApiDocumentationSource> javaApiDocumentationSources() {
+        return JAVA_API_DOCUMENTATION_SOURCES;
+    }
+
     private static Properties loadDocsSourceProperties() {
         final Properties docsSourceProperties = new Properties();
         try (InputStream inputStream = DocsSourceRegistry.class.getResourceAsStream(DOCS_SOURCES_RESOURCE)) {
@@ -153,15 +201,11 @@ private static String resolveSetting(final String settingKey, final String fallb
     private static Map<String, String> buildLocalPrefixLookup() {
         final Map<String, String> prefixLookup = new LinkedHashMap<>();
 
-        // Java SE 24 API (Oracle)
-        prefixLookup.put(LOCAL_DOCS_JAVA24, JAVA24_API_BASE);
-        prefixLookup.put(LOCAL_DOCS_JAVA24_NESTED, JAVA24_API_BASE);
-        prefixLookup.put(LOCAL_DOCS_JAVA24_COMPLETE, JAVA24_API_BASE);
-
-        // Java SE 25 documentation (Oracle) - includes alternate local paths for backwards compatibility
-        prefixLookup.put(LOCAL_DOCS_JAVA25, JAVA25_API_BASE);
-        prefixLookup.put(LOCAL_DOCS_JAVA25_NESTED, JAVA25_API_BASE);
-        prefixLookup.put(LOCAL_DOCS_JAVA25_COMPLETE, JAVA25_API_BASE);
+        for (JavaApiDocumentationSource javaApiDocumentationSource : JAVA_API_DOCUMENTATION_SOURCES) {
+            prefixLookup.put(
+                    LOCAL_DOCS_ROOT + javaApiDocumentationSource.relativeMirrorPath() + "/",
+                    javaApiDocumentationSource.remoteBaseUrl());
+        }
 
         // Spring Boot documentation
         prefixLookup.put(LOCAL_DOCS_SPRING_BOOT, SPRING_BOOT_BASE);
diff --git a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
new file mode 100644
index 00000000..c9b25a51
--- /dev/null
+++ b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
@@ -0,0 +1,180 @@
+package com.williamcallahan.javachat.config;
+
+import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Interprets the canonical complete-Java documentation source manifest.
+ *
+ * <p>The resource owns source rows; this boundary enforces one byte-stable grammar before exposing
+ * typed projections to the application.</p>
+ */
+final class JavaApiDocumentationManifest {
+
+    private static final String MANIFEST_RESOURCE = "/java-api-documentation-sources.manifest";
+    private static final String MANIFEST_DELIMITER = "|";
+    private static final String MANIFEST_DELIMITER_REGEX = "\\|";
+    private static final Pattern CANONICAL_UNSIGNED_INTEGER = Pattern.compile("(?:0|[1-9][0-9]*)");
+
+    private JavaApiDocumentationManifest() {}
+
+    static List<JavaApiDocumentationSource> load() {
+        InputStream manifestStream = JavaApiDocumentationManifest.class.getResourceAsStream(MANIFEST_RESOURCE);
+        if (manifestStream == null) {
+            throw new IllegalStateException("Canonical Java API documentation source manifest is missing");
+        }
+
+        try (manifestStream;
+                BufferedReader manifestReader =
+                        new BufferedReader(new InputStreamReader(manifestStream, StandardCharsets.UTF_8))) {
+            return parse(manifestReader.lines().toList());
+        } catch (IOException manifestReadError) {
+            throw new IllegalStateException(
+                    "Canonical Java API documentation source manifest could not be read", manifestReadError);
+        }
+    }
+
+    static List<JavaApiDocumentationSource> parse(List<String> manifestLines) {
+        if (manifestLines.size() < 2) {
+            throw new IllegalStateException("Canonical Java API documentation source manifest has no records");
+        }
+        validateHeader(manifestLines.get(0));
+
+        List<JavaApiDocumentationSource> sources = new ArrayList<>();
+        Set<String> retainedJavaReleases = new HashSet<>();
+        Set<String> retainedRelativeMirrorPaths = new HashSet<>();
+        for (int manifestLineIndex = 1; manifestLineIndex < manifestLines.size(); manifestLineIndex++) {
+            int manifestLineNumber = manifestLineIndex + 1;
+            String manifestLine = manifestLines.get(manifestLineIndex);
+            if (manifestLine.isBlank()) {
+                throw invalidLine(manifestLineNumber, "cannot be blank");
+            }
+
+            JavaApiDocumentationSource source = parseSource(manifestLine, manifestLineNumber);
+            if (!retainedJavaReleases.add(source.javaRelease())) {
+                throw invalidLine(manifestLineNumber, "duplicates Java release " + source.javaRelease());
+            }
+            if (!retainedRelativeMirrorPaths.add(source.relativeMirrorPath())) {
+                throw invalidLine(manifestLineNumber, "duplicates mirror path " + source.relativeMirrorPath());
+            }
+            sources.add(source);
+        }
+        return List.copyOf(sources);
+    }
+
+    static int requireCanonicalUnsignedInteger(String integerText, String fieldName) {
+        if (integerText == null
+                || !CANONICAL_UNSIGNED_INTEGER.matcher(integerText).matches()) {
+            throw new IllegalArgumentException(fieldName + " must be a canonical ASCII unsigned integer");
+        }
+        try {
+            return Integer.parseInt(integerText);
+        } catch (NumberFormatException integerOverflow) {
+            throw new IllegalArgumentException(fieldName + " exceeds the supported integer range", integerOverflow);
+        }
+    }
+
+    static void requireManifestText(String manifestText, String fieldName, boolean allowEmpty) {
+        if (manifestText == null) {
+            throw new IllegalArgumentException(fieldName + " cannot be null");
+        }
+        if (!allowEmpty && manifestText.isEmpty()) {
+            throw new IllegalArgumentException(fieldName + " cannot be blank");
+        }
+        if (!allowEmpty && hasBoundaryWhitespace(manifestText)) {
+            throw new IllegalArgumentException(fieldName + " cannot have boundary whitespace");
+        }
+    }
+
+    static String serialize(JavaApiDocumentationSource source) {
+        return String.join(
+                MANIFEST_DELIMITER,
+                source.javaRelease(),
+                source.remoteBaseUrl(),
+                source.relativeMirrorPath(),
+                source.displayName(),
+                Integer.toString(source.cutDirectories()),
+                Integer.toString(source.minimumHtmlFiles()),
+                source.rejectRegex(),
+                Boolean.toString(source.allowPartial()));
+    }
+
+    private static void validateHeader(String manifestHeader) {
+        String expectedHeader = Arrays.stream(JavaApiDocumentationSource.class.getRecordComponents())
+                .map(recordComponent -> recordComponent.getName())
+                .reduce((leftColumn, rightColumn) -> leftColumn + MANIFEST_DELIMITER + rightColumn)
+                .orElseThrow();
+        if (!expectedHeader.equals(manifestHeader)) {
+            throw new IllegalStateException("Canonical Java API documentation source manifest header is invalid");
+        }
+    }
+
+    private static JavaApiDocumentationSource parseSource(String manifestLine, int manifestLineNumber) {
+        List<String> sourceColumns = List.of(manifestLine.split(MANIFEST_DELIMITER_REGEX, -1));
+        int sourceComponentCount = JavaApiDocumentationSource.class.getRecordComponents().length;
+        if (sourceColumns.size() != sourceComponentCount) {
+            throw invalidLine(manifestLineNumber, "has an invalid column count");
+        }
+
+        Iterator<String> sourceColumnIterator = sourceColumns.iterator();
+        try {
+            return new JavaApiDocumentationSource(
+                    sourceColumnIterator.next(),
+                    sourceColumnIterator.next(),
+                    sourceColumnIterator.next(),
+                    sourceColumnIterator.next(),
+                    requireCanonicalUnsignedInteger(sourceColumnIterator.next(), "cutDirectories"),
+                    requireCanonicalUnsignedInteger(sourceColumnIterator.next(), "minimumHtmlFiles"),
+                    sourceColumnIterator.next(),
+                    parseBoolean(sourceColumnIterator.next(), "allowPartial"));
+        } catch (IllegalArgumentException invalidField) {
+            throw new IllegalStateException(
+                    "Canonical Java API documentation source manifest line " + manifestLineNumber
+                            + " has an invalid field: " + invalidField.getMessage(),
+                    invalidField);
+        }
+    }
+
+    private static boolean parseBoolean(String booleanText, String fieldName) {
+        if ("true".equals(booleanText)) {
+            return true;
+        }
+        if ("false".equals(booleanText)) {
+            return false;
+        }
+        throw new IllegalArgumentException(fieldName + " must be true or false");
+    }
+
+    private static boolean hasBoundaryWhitespace(String manifestText) {
+        if (manifestText.isEmpty()) {
+            return false;
+        }
+        return isAsciiWhitespace(manifestText.charAt(0))
+                || isAsciiWhitespace(manifestText.charAt(manifestText.length() - 1));
+    }
+
+    private static boolean isAsciiWhitespace(char manifestCharacter) {
+        return manifestCharacter == ' '
+                || manifestCharacter == '\t'
+                || manifestCharacter == '\r'
+                || manifestCharacter == '\n'
+                || manifestCharacter == '\f'
+                || manifestCharacter == 0x0B;
+    }
+
+    private static IllegalStateException invalidLine(int manifestLineNumber, String problem) {
+        return new IllegalStateException(
+                "Canonical Java API documentation source manifest line " + manifestLineNumber + " " + problem);
+    }
+}
diff --git a/src/main/resources/docs-sources.properties b/src/main/resources/docs-sources.properties
index d426f460..deeb4ae8 100644
--- a/src/main/resources/docs-sources.properties
+++ b/src/main/resources/docs-sources.properties
@@ -1,10 +1,4 @@
-# Centralized documentation source URLs (single source of truth)
-
-# Oracle Java SE 24 API
-JAVA24_API_BASE=https://docs.oracle.com/en/java/javase/24/docs/api/
-
-# Oracle Java SE 25 Documentation
-JAVA25_API_BASE=https://docs.oracle.com/en/java/javase/25/docs/api/
+# Centralized sources outside complete Java API mirrors
 
 # Oracle Java SE release notes/issues
 ORACLE_JAVASE_BASE=https://www.oracle.com/java/technologies/javase/
diff --git a/src/main/resources/java-api-documentation-sources.manifest b/src/main/resources/java-api-documentation-sources.manifest
new file mode 100644
index 00000000..e0820a22
--- /dev/null
+++ b/src/main/resources/java-api-documentation-sources.manifest
@@ -0,0 +1,4 @@
+javaRelease|remoteBaseUrl|relativeMirrorPath|displayName|cutDirectories|minimumHtmlFiles|rejectRegex|allowPartial
+21|https://docs.oracle.com/en/java/javase/21/docs/api/|java/java21-complete|Java 21 Complete API|5|9000||true
+24|https://docs.oracle.com/en/java/javase/24/docs/api/|java/java24-complete|Java 24 Complete API|5|9000||true
+25|https://docs.oracle.com/en/java/javase/25/docs/api/|java/java25-complete|Java 25 Complete API|5|9000||true
diff --git a/src/test/java/com/williamcallahan/javachat/ExtractorQualityTest.java b/src/test/java/com/williamcallahan/javachat/ExtractorQualityTest.java
index c4f7ffad..6bd2fb4c 100644
--- a/src/test/java/com/williamcallahan/javachat/ExtractorQualityTest.java
+++ b/src/test/java/com/williamcallahan/javachat/ExtractorQualityTest.java
@@ -1,9 +1,11 @@
 package com.williamcallahan.javachat;
 
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.service.HtmlContentExtractor;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.stream.Collectors;
@@ -28,6 +30,8 @@
 @Profile("manual")
 public class ExtractorQualityTest {
 
+    private record ExtractionSource(String relativePath, String displayName) {}
+
     /**
      * Launches the extraction quality runner in non-web mode.
      *
@@ -51,29 +55,29 @@ CommandLineRunner testExtraction(HtmlContentExtractor extractor) {
         return args -> {
             String docsRoot = "data/docs";
 
-            // Test sources
-            String[][] sources = {
-                {"java/java24-complete", "Java 24"},
-                {"java/java25-complete", "Java 25"},
-                {"spring-boot-complete", "Spring Boot"},
-                {"spring-framework-complete", "Spring Framework"}
-            };
+            List<ExtractionSource> extractionSources =
+                    new ArrayList<>(DocsSourceRegistry.javaApiDocumentationSources().stream()
+                            .map(javaApiDocumentationSource -> new ExtractionSource(
+                                    javaApiDocumentationSource.relativeMirrorPath(),
+                                    javaApiDocumentationSource.displayName()))
+                            .toList());
+            extractionSources.add(new ExtractionSource("spring-boot-complete", "Spring Boot"));
+            extractionSources.add(new ExtractionSource("spring-framework-complete", "Spring Framework"));
 
             System.out.println("\n========================================");
             System.out.println("HTML EXTRACTION QUALITY CONTROL TEST");
             System.out.println("========================================\n");
 
-            for (String[] source : sources) {
-                String dir = source[0];
-                String name = source[1];
-                Path sourcePath = Paths.get(docsRoot, dir);
+            for (ExtractionSource extractionSource : extractionSources) {
+                String sourceDisplayName = extractionSource.displayName();
+                Path sourcePath = Paths.get(docsRoot, extractionSource.relativePath());
 
                 if (!Files.exists(sourcePath)) {
-                    System.out.println("⚠ Skipping " + name + " (not found)");
+                    System.out.println("⚠ Skipping " + sourceDisplayName + " (not found)");
                     continue;
                 }
 
-                System.out.println("\n=== Testing " + name + " ===");
+                System.out.println("\n=== Testing " + sourceDisplayName + " ===");
 
                 // Get sample files
                 List<Path> htmlFiles;
@@ -163,7 +167,7 @@ CommandLineRunner testExtraction(HtmlContentExtractor extractor) {
                 }
 
                 // Summary for this source
-                System.out.println("Summary for " + name + ":");
+                System.out.println("Summary for " + sourceDisplayName + ":");
                 System.out.println("  Total noise patterns: " + totalOldNoise + " → " + totalNewNoise + " ("
                         + (totalOldNoise - totalNewNoise) + " removed)");
                 double avgReduction = totalOldLength > 0 ? (1.0 - (double) totalNewLength / totalOldLength) * 100 : 0;
diff --git a/src/test/java/com/williamcallahan/javachat/StandaloneExtractionTest.java b/src/test/java/com/williamcallahan/javachat/StandaloneExtractionTest.java
index 3fda8f2e..418a5f5f 100644
--- a/src/test/java/com/williamcallahan/javachat/StandaloneExtractionTest.java
+++ b/src/test/java/com/williamcallahan/javachat/StandaloneExtractionTest.java
@@ -1,5 +1,6 @@
 package com.williamcallahan.javachat;
 
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.service.HtmlContentExtractor;
 import com.williamcallahan.javachat.support.AsciiTextNormalizer;
 import java.io.IOException;
@@ -19,6 +20,8 @@
  */
 public class StandaloneExtractionTest {
 
+    private record ExtractionSource(String relativePath, String displayName) {}
+
     /**
      * Runs the extraction comparison against sampled documentation files.
      *
@@ -29,13 +32,14 @@ public static void main(String[] args) throws IOException {
         HtmlContentExtractor extractor = new HtmlContentExtractor();
         String docsRoot = "data/docs";
 
-        // Test sources
-        String[][] sources = {
-            {"java/java24-complete", "Java 24"},
-            {"java/java25-complete", "Java 25"},
-            {"spring-boot-complete", "Spring Boot"},
-            {"spring-framework-complete", "Spring Framework"}
-        };
+        List<ExtractionSource> extractionSources =
+                new ArrayList<>(DocsSourceRegistry.javaApiDocumentationSources().stream()
+                        .map(javaApiDocumentationSource -> new ExtractionSource(
+                                javaApiDocumentationSource.relativeMirrorPath(),
+                                javaApiDocumentationSource.displayName()))
+                        .toList());
+        extractionSources.add(new ExtractionSource("spring-boot-complete", "Spring Boot"));
+        extractionSources.add(new ExtractionSource("spring-framework-complete", "Spring Framework"));
 
         System.out.println("\n========================================");
         System.out.println("HTML EXTRACTION QUALITY CONTROL TEST");
@@ -45,17 +49,16 @@ public static void main(String[] args) throws IOException {
         int grandTotalNewNoise = 0;
         List<String> problematicFiles = new ArrayList<>();
 
-        for (String[] source : sources) {
-            String dir = source[0];
-            String name = source[1];
-            Path sourcePath = Paths.get(docsRoot, dir);
+        for (ExtractionSource extractionSource : extractionSources) {
+            String sourceDisplayName = extractionSource.displayName();
+            Path sourcePath = Paths.get(docsRoot, extractionSource.relativePath());
 
             if (!Files.exists(sourcePath)) {
-                System.out.println("⚠ Skipping " + name + " (not found)");
+                System.out.println("⚠ Skipping " + sourceDisplayName + " (not found)");
                 continue;
             }
 
-            System.out.println("\n=== Testing " + name + " ===");
+            System.out.println("\n=== Testing " + sourceDisplayName + " ===");
 
             // Get sample files
             List<Path> htmlFiles;
@@ -157,7 +160,7 @@ public static void main(String[] args) throws IOException {
             }
 
             // Summary for this source
-            System.out.println("Summary for " + name + ":");
+            System.out.println("Summary for " + sourceDisplayName + ":");
             System.out.println("  Total noise patterns: " + totalOldNoise + " → " + totalNewNoise + " ("
                     + (totalOldNoise - totalNewNoise) + " removed)");
 
diff --git a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
new file mode 100644
index 00000000..0151426a
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
@@ -0,0 +1,57 @@
+package com.williamcallahan.javachat.cli;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
+import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that CLI and shell ingestion project the canonical Java API source inventory.
+ */
+class JavaApiDocumentationSourceParityTest {
+
+    @Test
+    void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOException, InterruptedException {
+        List<JavaApiDocumentationSource> canonicalJavaApiSources = DocsSourceRegistry.javaApiDocumentationSources();
+        List<DocumentationSet> expectedCliDocumentationSets = canonicalJavaApiSources.stream()
+                .map(javaApiDocumentationSource -> new DocumentationSet(
+                        javaApiDocumentationSource.displayName(), javaApiDocumentationSource.relativeMirrorPath()))
+                .toList();
+        List<DocumentationSet> actualCliDocumentationSets = DocumentationSetCatalog.baseSets().stream()
+                .filter(expectedCliDocumentationSets::contains)
+                .toList();
+
+        assertEquals(expectedCliDocumentationSets, actualCliDocumentationSets);
+
+        Path fetchScriptPath = Path.of("scripts", "fetch_all_docs.sh").toAbsolutePath();
+        ProcessBuilder fetchSourceListingCommand =
+                new ProcessBuilder("/bin/bash", fetchScriptPath.toString(), "--list-java-api-sources");
+        fetchSourceListingCommand.redirectErrorStream(true);
+        Process fetchSourceListingProcess = fetchSourceListingCommand.start();
+        String scriptStandardOutput =
+                new String(fetchSourceListingProcess.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
+        int scriptExitCode = fetchSourceListingProcess.waitFor();
+
+        assertEquals(0, scriptExitCode, scriptStandardOutput);
+        Path sourceManifestPath = Path.of("src", "main", "resources", "java-api-documentation-sources.manifest");
+        List<String> manifestSourceRows = Files.readAllLines(sourceManifestPath, StandardCharsets.UTF_8).stream()
+                .filter(manifestLine -> !manifestLine.isBlank())
+                .skip(1)
+                .toList();
+        List<String> actualScriptProjections = scriptStandardOutput
+                .lines()
+                .filter(scriptOutputLine -> !scriptOutputLine.isBlank())
+                .toList();
+        List<String> actualJavaProjections = canonicalJavaApiSources.stream()
+                .map(JavaApiDocumentationSource::toManifestRow)
+                .toList();
+        assertEquals(manifestSourceRows, actualJavaProjections);
+        assertEquals(manifestSourceRows, actualScriptProjections);
+    }
+}
diff --git a/src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java b/src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java
new file mode 100644
index 00000000..22197ab8
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java
@@ -0,0 +1,37 @@
+package com.williamcallahan.javachat.config;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that Java API citation mappings project the canonical documentation source manifest.
+ */
+class DocsSourceRegistryTest {
+
+    @Test
+    void mapsEveryCanonicalJavaApiMirrorToItsRemoteBaseUrl() {
+        List<JavaApiDocumentationSource> javaApiDocumentationSources = DocsSourceRegistry.javaApiDocumentationSources();
+        javaApiDocumentationSources.forEach(javaApiDocumentationSource -> {
+            String localJavadocFileUrl = "file:///data/docs/" + javaApiDocumentationSource.relativeMirrorPath()
+                    + "/api/java.base/java/lang/String.html";
+            String expectedOfficialJavadocUrl =
+                    javaApiDocumentationSource.remoteBaseUrl() + "java.base/java/lang/String.html";
+            assertEquals(expectedOfficialJavadocUrl, DocsSourceRegistry.normalizeDocUrl(localJavadocFileUrl));
+        });
+        assertEquals(
+                javaApiDocumentationSources.size(),
+                javaApiDocumentationSources.stream()
+                        .map(JavaApiDocumentationSource::javaRelease)
+                        .distinct()
+                        .count());
+        assertEquals(
+                javaApiDocumentationSources.size(),
+                javaApiDocumentationSources.stream()
+                        .map(JavaApiDocumentationSource::relativeMirrorPath)
+                        .distinct()
+                        .count());
+    }
+}
diff --git a/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
new file mode 100644
index 00000000..d8626402
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
@@ -0,0 +1,106 @@
+package com.williamcallahan.javachat.config;
+
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/** Verifies that JVM and Bash boundaries reject the same malformed canonical manifests. */
+class JavaApiDocumentationManifestTest {
+
+    private static final Path CANONICAL_MANIFEST_PATH =
+            Path.of("src", "main", "resources", "java-api-documentation-sources.manifest");
+    private static final Path SHELL_INTERPRETER_PATH = Path.of("scripts", "lib", "documentation_sources.sh");
+
+    @TempDir
+    Path temporaryDirectory;
+
+    @Test
+    void rejectsSharedInvalidManifestFixturesInJavaAndBash() throws IOException, InterruptedException {
+        List<String> canonicalManifestLines = Files.readAllLines(CANONICAL_MANIFEST_PATH, StandardCharsets.UTF_8);
+        List<List<String>> invalidManifestFixtures = List.of(
+                withLine(canonicalManifestLines, 0, "invalidHeader"),
+                withInsertedLine(canonicalManifestLines, 2, " "),
+                withLine(
+                        canonicalManifestLines,
+                        1,
+                        canonicalManifestLines
+                                .get(1)
+                                .substring(0, canonicalManifestLines.get(1).lastIndexOf('|'))),
+                withColumn(canonicalManifestLines, 1, 1, " https://docs.oracle.com/invalid/"),
+                withColumn(canonicalManifestLines, 1, 2, ""),
+                withColumn(canonicalManifestLines, 1, 4, "+5"),
+                withColumn(canonicalManifestLines, 1, 4, "05"),
+                withColumn(canonicalManifestLines, 1, 5, "2147483648"),
+                withColumn(canonicalManifestLines, 1, 7, "TRUE"),
+                withDuplicateRelease(canonicalManifestLines),
+                withDuplicateMirrorPath(canonicalManifestLines));
+
+        for (int fixtureIndex = 0; fixtureIndex < invalidManifestFixtures.size(); fixtureIndex++) {
+            List<String> invalidManifestLines = invalidManifestFixtures.get(fixtureIndex);
+            assertThrows(
+                    IllegalStateException.class,
+                    () -> JavaApiDocumentationManifest.parse(invalidManifestLines),
+                    "Java accepted invalid fixture " + fixtureIndex);
+
+            Path invalidManifestPath = temporaryDirectory.resolve("invalid-manifest-" + fixtureIndex + ".manifest");
+            Files.write(invalidManifestPath, invalidManifestLines, StandardCharsets.UTF_8);
+            Process bashValidation = new ProcessBuilder(
+                            "/bin/bash",
+                            "-c",
+                            "source \"$1\"; load_java_api_documentation_sources \"$2\"",
+                            "manifest-validation",
+                            SHELL_INTERPRETER_PATH.toAbsolutePath().toString(),
+                            invalidManifestPath.toString())
+                    .redirectErrorStream(true)
+                    .start();
+            String bashOutput = new String(bashValidation.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
+            int bashExitCode = bashValidation.waitFor();
+            assertNotEquals(0, bashExitCode, "Bash accepted invalid fixture " + fixtureIndex + ": " + bashOutput);
+        }
+    }
+
+    private static List<String> withLine(List<String> manifestLines, int lineIndex, String replacementLine) {
+        List<String> changedManifestLines = new ArrayList<>(manifestLines);
+        changedManifestLines.set(lineIndex, replacementLine);
+        return List.copyOf(changedManifestLines);
+    }
+
+    private static List<String> withInsertedLine(List<String> manifestLines, int lineIndex, String insertedLine) {
+        List<String> changedManifestLines = new ArrayList<>(manifestLines);
+        changedManifestLines.add(lineIndex, insertedLine);
+        return List.copyOf(changedManifestLines);
+    }
+
+    private static List<String> withColumn(
+            List<String> manifestLines, int lineIndex, int columnIndex, String replacementColumn) {
+        String[] sourceColumns = manifestLines.get(lineIndex).split("\\|", -1);
+        sourceColumns[columnIndex] = replacementColumn;
+        return withLine(manifestLines, lineIndex, String.join("|", sourceColumns));
+    }
+
+    private static List<String> withDuplicateRelease(List<String> manifestLines) {
+        String[] duplicateReleaseColumns = manifestLines.get(1).split("\\|", -1);
+        duplicateReleaseColumns[2] = duplicateReleaseColumns[2] + "-duplicate";
+        List<String> changedManifestLines = new ArrayList<>(manifestLines);
+        changedManifestLines.add(String.join("|", duplicateReleaseColumns));
+        return List.copyOf(changedManifestLines);
+    }
+
+    private static List<String> withDuplicateMirrorPath(List<String> manifestLines) {
+        String[] duplicateMirrorColumns = manifestLines.get(1).split("\\|", -1);
+        String[] finalSourceColumns =
+                manifestLines.get(manifestLines.size() - 1).split("\\|", -1);
+        duplicateMirrorColumns[0] = Integer.toString(Integer.parseInt(finalSourceColumns[0]) + 1);
+        List<String> changedManifestLines = new ArrayList<>(manifestLines);
+        changedManifestLines.add(String.join("|", duplicateMirrorColumns));
+        return List.copyOf(changedManifestLines);
+    }
+}

From f24081c8ccfa51efe3cf351909edfcd81f94326f Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 11:53:30 -0700
Subject: [PATCH 02/40] fix(retrieval): preserve same-page chunks before
 citation dedupe

Deduplicate candidates by the strongest available identity so reranking keeps
distinct chunks from one page. Collapse final citations by canonical source URL.
---
 .../javachat/service/RetrievalService.java    | 71 ++++++++++++-------
 .../service/RetrievalServiceTest.java         | 64 +++++++++++++++++
 2 files changed, 109 insertions(+), 26 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java b/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
index 0644de2e..f1e967f1 100644
--- a/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
@@ -7,10 +7,11 @@
 import com.williamcallahan.javachat.util.QueryVersionExtractor;
 import com.williamcallahan.javachat.util.QueryVersionExtractor.VersionFilterPatterns;
 import java.util.ArrayList;
-import java.util.LinkedHashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.ai.document.Document;
@@ -35,6 +36,7 @@ public class RetrievalService {
     private static final String METADATA_TITLE = "title";
     private static final String METADATA_PACKAGE = "package";
     private static final String METADATA_HASH = "hash";
+    private static final char URL_FRAGMENT_DELIMITER = '#';
 
     private final HybridSearchService hybridSearchService;
     private final AppProperties appProperties;
@@ -117,10 +119,10 @@ public RetrievalOutcome retrieveOutcome(String query) {
         List<Document> filtered = retrievalConstraint.hasServerSideConstraint()
                 ? candidates
                 : applyVersionFilterIfPresent(versionFilter, candidates);
-        List<Document> uniqueByHash = dedupeByHashThenUrl(filtered);
+        List<Document> deduplicatedCandidates = deduplicateByContentHashThenHashlessCanonicalUrl(filtered);
 
         List<Document> reranked = rerankerService.rerank(
-                query, uniqueByHash, appProperties.getRag().getSearchReturnK());
+                query, deduplicatedCandidates, appProperties.getRag().getSearchReturnK());
 
         if (!reranked.isEmpty()) {
             Map<String, ?> firstDocMetadata = reranked.get(0).getMetadata();
@@ -182,37 +184,43 @@ private static RetrievalConstraint toRetrievalConstraint(Optional<VersionFilterP
         return RetrievalConstraint.forDocVersion(versionNumber);
     }
 
-    private List<Document> dedupeByHashThenUrl(List<Document> documents) {
+    private List<Document> deduplicateByContentHashThenHashlessCanonicalUrl(List<Document> documents) {
         if (documents.isEmpty()) {
             return documents;
         }
-        Map<String, Document> byHash = new LinkedHashMap<>();
-        List<Document> withoutHash = new ArrayList<>();
+        Set<String> retainedContentHashes = new HashSet<>();
+        Set<String> retainedHashlessCanonicalUrls = new HashSet<>();
+        List<Document> deduplicatedDocuments = new ArrayList<>(documents.size());
+        int unidentifiedDocumentCount = 0;
         for (Document document : documents) {
-            String hash = stringMetadataValue(document.getMetadata(), METADATA_HASH);
-            if (!hash.isBlank()) {
-                byHash.putIfAbsent(hash, document);
+            String contentHash = stringMetadataValue(document.getMetadata(), METADATA_HASH);
+            if (!contentHash.isBlank()) {
+                if (!retainedContentHashes.add(contentHash)) {
+                    continue;
+                }
             } else {
-                withoutHash.add(document);
-            }
-        }
-        Map<String, Document> byUrl = new LinkedHashMap<>();
-        List<Document> unidentified = new ArrayList<>();
-        for (Document document : withoutHash) {
-            String url = stringMetadataValue(document.getMetadata(), METADATA_URL);
-            if (!url.isBlank()) {
-                byUrl.putIfAbsent(url, document);
-            } else {
-                unidentified.add(document);
+                String documentUrl = stringMetadataValue(document.getMetadata(), METADATA_URL)
+                        .trim();
+                if (!documentUrl.isBlank()) {
+                    String canonicalDocumentUrl = documentUrl.startsWith("file://")
+                            ? DocsSourceRegistry.resolveLocalPath(documentUrl.substring("file://".length()))
+                                    .map(DocsSourceRegistry::canonicalizeHttpDocUrl)
+                                    .orElse(documentUrl)
+                            : DocsSourceRegistry.normalizeDocUrl(documentUrl);
+                    if (!retainedHashlessCanonicalUrls.add(canonicalDocumentUrl)) {
+                        continue;
+                    }
+                } else {
+                    unidentifiedDocumentCount++;
+                }
             }
+
+            deduplicatedDocuments.add(document);
         }
-        if (!unidentified.isEmpty()) {
-            log.warn("Dedup kept {} documents with neither hash nor URL metadata", unidentified.size());
+        if (unidentifiedDocumentCount > 0) {
+            log.warn("Dedup kept {} documents with neither hash nor URL metadata", unidentifiedDocumentCount);
         }
-        List<Document> combined = new ArrayList<>(byHash.values());
-        combined.addAll(byUrl.values());
-        combined.addAll(unidentified);
-        return List.copyOf(combined);
+        return List.copyOf(deduplicatedDocuments);
     }
 
     private static String stringMetadataValue(Map<String, ?> metadata, String key) {
@@ -274,6 +282,7 @@ public CitationOutcome toCitations(List<Document> documents) {
             return new CitationOutcome(List.of(), 0);
         }
         List<Citation> citations = new ArrayList<>();
+        Set<String> retainedCitationUrls = new HashSet<>();
         int failedConversionCount = 0;
         for (Document sourceDocument : documents) {
             if (sourceDocument == null) {
@@ -285,6 +294,11 @@ public CitationOutcome toCitations(List<Document> documents) {
                 String title = stringMetadataValue(sourceDocMetadata, METADATA_TITLE);
                 String packageName = stringMetadataValue(sourceDocMetadata, METADATA_PACKAGE);
                 String url = refineCitationUrl(rawUrl, sourceDocument.getText(), packageName);
+                String fragmentlessCitationSourceUrl = fragmentlessCitationSourceUrl(url);
+                if (!fragmentlessCitationSourceUrl.isBlank()
+                        && !retainedCitationUrls.add(fragmentlessCitationSourceUrl)) {
+                    continue;
+                }
                 citations.add(new Citation(url, title, "", trimmedCitationSnippet(sourceDocument.getText())));
             } catch (RuntimeException citationConversionFailure) {
                 failedConversionCount++;
@@ -305,6 +319,11 @@ public CitationOutcome toCitations(List<Document> documents) {
         return new CitationOutcome(citations, failedConversionCount);
     }
 
+    private static String fragmentlessCitationSourceUrl(String citationUrl) {
+        int fragmentDelimiterIndex = citationUrl.indexOf(URL_FRAGMENT_DELIMITER);
+        return fragmentDelimiterIndex < 0 ? citationUrl : citationUrl.substring(0, fragmentDelimiterIndex);
+    }
+
     /**
      * Refines a raw document URL through nested-type and member-anchor resolution, then canonicalizes.
      *
diff --git a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
index fb46621c..b62964a9 100644
--- a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
@@ -48,6 +48,70 @@ void propagatesHybridSearchNotices() {
                 "Partial retrieval failure", retrievalOutcome.notices().get(0).summary());
     }
 
+    @Test
+    void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations() {
+        HybridSearchService hybridSearchService = mock(HybridSearchService.class);
+        RerankerService rerankerService = mock(RerankerService.class);
+        DocumentFactory documentFactory = mock(DocumentFactory.class);
+        AppProperties appProperties = new AppProperties();
+        RetrievalService retrievalService =
+                new RetrievalService(hybridSearchService, appProperties, rerankerService, documentFactory);
+
+        Document urlOnlyDocument = Document.builder()
+                .id("url-only")
+                .text("URL-only candidate")
+                .metadata("url", "https://example.org/java/reference")
+                .build();
+        Document canonicalUrlDuplicateWithoutHash = Document.builder()
+                .id("url-only-duplicate")
+                .text("URL-only duplicate candidate")
+                .metadata("url", "https://example.org//java/reference")
+                .build();
+        Document firstJavadocChunk = Document.builder()
+                .id("first-javadoc-chunk")
+                .text("First Javadoc chunk")
+                .metadata("url", "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html")
+                .metadata("hash", "first-content-hash")
+                .build();
+        Document secondJavadocChunkWithDistinctHash = Document.builder()
+                .id("second-javadoc-chunk")
+                .text("Second Javadoc chunk")
+                .metadata("url", "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html#assert(...)")
+                .metadata("hash", "second-content-hash")
+                .build();
+        Document sameContentHashWithDifferentUrl = Document.builder()
+                .id("same-content-hash")
+                .text("Duplicate content under another URL")
+                .metadata("url", "https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html")
+                .metadata("hash", "first-content-hash")
+                .build();
+        List<Document> retrievalCandidates = List.of(
+                urlOnlyDocument,
+                canonicalUrlDuplicateWithoutHash,
+                firstJavadocChunk,
+                secondJavadocChunkWithDistinctHash,
+                sameContentHashWithDifferentUrl);
+        when(hybridSearchService.searchOutcome(anyString(), anyInt(), any(RetrievalConstraint.class)))
+                .thenReturn(new HybridSearchService.SearchOutcome(retrievalCandidates, List.of()));
+        when(rerankerService.rerank(anyString(), anyList(), anyInt())).thenAnswer(rerankerInvocation -> {
+            List<Document> deduplicatedCandidates = rerankerInvocation.getArgument(1);
+            return deduplicatedCandidates;
+        });
+
+        RetrievalService.RetrievalOutcome retrievalOutcome = retrievalService.retrieveOutcome("Java string basics");
+        RetrievalService.CitationOutcome citationOutcome = retrievalService.toCitations(retrievalOutcome.documents());
+
+        assertEquals(
+                List.of(urlOnlyDocument, firstJavadocChunk, secondJavadocChunkWithDistinctHash),
+                retrievalOutcome.documents());
+        assertEquals(2, citationOutcome.citations().size());
+        assertEquals(
+                "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html",
+                citationOutcome.citations().get(1).getUrl());
+        assertEquals("First Javadoc chunk", citationOutcome.citations().get(1).getSnippet());
+        assertEquals(0, citationOutcome.failedConversionCount());
+    }
+
     @Test
     void propagatesStrictHybridSearchFailure() {
         HybridSearchService hybridSearchService = mock(HybridSearchService.class);

From 8152d791bb562ca52dfef263042d43dd7ba60338 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 11:58:05 -0700
Subject: [PATCH 03/40] fix(streaming): prevent stateful chat replay

Persist completed exchanges atomically and emit provider fallback state from one canonical notice stream. Remove client-side POST replay so failed stateful requests cannot duplicate chat or lesson work.
---
 .../domains/all-parsing-and-markdown-logic.md |   2 +-
 frontend/src/lib/components/ChatView.test.ts  |  21 ++
 .../createStreamingState.svelte.ts            |   5 +-
 frontend/src/lib/services/chat.test.ts        |  55 ++--
 frontend/src/lib/services/chat.ts             |   8 +-
 frontend/src/lib/services/guided.test.ts      |  45 ++-
 frontend/src/lib/services/guided.ts           |   9 +-
 .../src/lib/services/streamRecovery.test.ts   | 166 ----------
 frontend/src/lib/services/streamRecovery.ts   | 289 ------------------
 .../javachat/service/ChatMemoryService.java   |  35 +--
 .../service/OpenAIStreamingService.java       |  26 +-
 .../service/OpenAiProviderRoutingService.java |  33 +-
 .../service/StreamingAttemptContext.java      |  14 +-
 .../javachat/service/StreamingResult.java     |   6 +-
 .../javachat/web/ChatController.java          |  15 +-
 .../web/GuidedLearningController.java         |  14 +-
 .../javachat/web/SseSupport.java              |  34 ++-
 .../service/ChatMemoryServiceTest.java        |  59 ++--
 .../service/OpenAIStreamingServiceTest.java   |  66 ++--
 .../service/StreamingAttemptContextTest.java  |  11 +-
 .../ChatControllerSessionValidationTest.java  |   2 +-
 .../ChatControllerStreamingFailureTest.java   |   5 +-
 ...earningControllerStreamingFailureTest.java |   4 +-
 .../web/GuidedSseCitationEventTest.java       |   4 +-
 ...StreamingProviderFallbackSseEventTest.java |  59 +++-
 25 files changed, 294 insertions(+), 693 deletions(-)
 delete mode 100644 frontend/src/lib/services/streamRecovery.test.ts
 delete mode 100644 frontend/src/lib/services/streamRecovery.ts

diff --git a/docs/domains/all-parsing-and-markdown-logic.md b/docs/domains/all-parsing-and-markdown-logic.md
index 9d5a59bf..18bd889e 100644
--- a/docs/domains/all-parsing-and-markdown-logic.md
+++ b/docs/domains/all-parsing-and-markdown-logic.md
@@ -41,7 +41,7 @@ This document provides a comprehensive analysis of all parsing and markdown proc
 │   ├── ChatController.stream() → SSE events
 │   ├── normalizeDelta() - token joining/cleanup
 │   ├── UnifiedMarkdownService.process() - final markdown processing
-│   └── ChatMemoryService.addAssistant() - persistence
+│   └── ChatMemoryService.addExchange() - atomic user/assistant persistence
 │
 └── 🔄 KEY TRANSITIONS & ISSUES
     ├── Regex → AST migration (incomplete)
diff --git a/frontend/src/lib/components/ChatView.test.ts b/frontend/src/lib/components/ChatView.test.ts
index 25ba4831..605ed91c 100644
--- a/frontend/src/lib/components/ChatView.test.ts
+++ b/frontend/src/lib/components/ChatView.test.ts
@@ -70,4 +70,25 @@ describe("ChatView streaming stability", () => {
     expect(assistantMessageElementAfter).toBe(assistantMessageElement);
     expect(container.querySelector(".message.assistant .cursor.visible")).toBeNull();
   });
+
+  it("shows the active fallback provider from structured stream status", async () => {
+    streamChatMock.mockImplementation(async (_sessionId, _message, _onChunk, options) => {
+      options?.onStatus?.({
+        message: "Retrying stream with provider",
+        details: "The first provider failed before response text.",
+        provider: "fallback-provider",
+      });
+      return new Promise<void>(() => {});
+    });
+
+    const { getByLabelText, getByRole, findByText } = await renderChatView();
+    const messageInput = getByLabelText("Message input");
+    if (!(messageInput instanceof HTMLTextAreaElement)) {
+      throw new Error("Expected message input element to be a textarea");
+    }
+    await fireEvent.input(messageInput, { target: { value: "Explain records" } });
+    await fireEvent.click(getByRole("button", { name: "Send message" }));
+
+    expect(await findByText(/Provider: fallback-provider/)).toBeTruthy();
+  });
 });
diff --git a/frontend/src/lib/composables/createStreamingState.svelte.ts b/frontend/src/lib/composables/createStreamingState.svelte.ts
index 5a384d59..4f94d19f 100644
--- a/frontend/src/lib/composables/createStreamingState.svelte.ts
+++ b/frontend/src/lib/composables/createStreamingState.svelte.ts
@@ -133,7 +133,10 @@ export function createStreamingState(options: StreamingStateOptions = {}): Strea
 
     updateStatus(status: StreamStatus) {
       statusMessage = status.message;
-      statusDetails = status.details ?? "";
+      const providerDescription = status.provider ? `Provider: ${status.provider}` : "";
+      statusDetails = [status.details ?? "", providerDescription]
+        .filter((statusDescription) => statusDescription.length > 0)
+        .join(" · ");
     },
 
     finishStream() {
diff --git a/frontend/src/lib/services/chat.test.ts b/frontend/src/lib/services/chat.test.ts
index c05f620a..881903af 100644
--- a/frontend/src/lib/services/chat.test.ts
+++ b/frontend/src/lib/services/chat.test.ts
@@ -10,43 +10,55 @@ vi.mock("./sse", () => {
 
 import { streamChat } from "./chat";
 
-describe("streamChat recovery", () => {
+describe("streamChat", () => {
   beforeEach(() => {
     streamSseMock.mockReset();
   });
 
-  it("retries once for recoverable overflow failure before any streamed chunk", async () => {
-    streamSseMock.mockRejectedValueOnce(new Error("OverflowException: malformed response frame"));
+  it("surfaces a recoverable stream failure without replaying the POST", async () => {
+    const streamFailure = {
+      message: "OverflowException: malformed response frame",
+      details: "Malformed response frame at byte 512",
+    };
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
-      callbacks.onText("Recovered response");
+      callbacks.onError?.(streamFailure);
+      throw new Error(streamFailure.message);
     });
 
     const onChunk = vi.fn();
     const onStatus = vi.fn();
     const onError = vi.fn();
+    const streamAbortController = new AbortController();
 
     await expect(
-      streamChat("session-1", "What is new in Java 25?", onChunk, { onStatus, onError }),
-    ).resolves.toBeUndefined();
-
-    expect(streamSseMock).toHaveBeenCalledTimes(2);
-    expect(onStatus).toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: "Temporary stream issue detected",
+      streamChat("session-1", "What is new in Java 25?", onChunk, {
+        onStatus,
+        onError,
+        signal: streamAbortController.signal,
       }),
-    );
-    expect(onStatus).toHaveBeenCalledWith(
+    ).rejects.toThrow("OverflowException: malformed response frame");
+
+    expect(streamSseMock).toHaveBeenCalledTimes(1);
+    expect(streamSseMock).toHaveBeenCalledWith(
+      "/api/chat/stream",
+      { sessionId: "session-1", latest: "What is new in Java 25?" },
       expect.objectContaining({
-        message: "Streaming recovered",
+        onText: onChunk,
+        onStatus,
+        onError,
       }),
+      "chat.ts",
+      { signal: streamAbortController.signal },
     );
-    expect(onChunk).toHaveBeenCalledWith("Recovered response");
-    expect(onError).not.toHaveBeenCalled();
+    expect(onStatus).not.toHaveBeenCalled();
+    expect(onChunk).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledWith(streamFailure);
   });
 
-  it("does not retry when a chunk already streamed to the UI", async () => {
+  it("does not replay after a stream has emitted a chunk", async () => {
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
       callbacks.onText("Partial answer");
+      callbacks.onError?.({ message: "OverflowException: malformed response frame" });
       throw new Error("OverflowException: malformed response frame");
     });
 
@@ -60,17 +72,12 @@ describe("streamChat recovery", () => {
 
     expect(streamSseMock).toHaveBeenCalledTimes(1);
     expect(onChunk).toHaveBeenCalledWith("Partial answer");
-    expect(onStatus).not.toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: "Temporary stream issue detected",
-      }),
-    );
     expect(onError).toHaveBeenCalledWith({
       message: "OverflowException: malformed response frame",
     });
   });
 
-  it("honors backend non-retryable stream status metadata", async () => {
+  it("forwards backend non-retryable stream status metadata without replaying", async () => {
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
       callbacks.onStatus?.({
         message: "Provider returned fatal stream error",
@@ -78,6 +85,7 @@ describe("streamChat recovery", () => {
         retryable: false,
         stage: "stream",
       });
+      callbacks.onError?.({ message: "Unexpected provider failure" });
       throw new Error("Unexpected provider failure");
     });
 
@@ -96,5 +104,6 @@ describe("streamChat recovery", () => {
         retryable: false,
       }),
     );
+    expect(onError).toHaveBeenCalledWith({ message: "Unexpected provider failure" });
   });
 });
diff --git a/frontend/src/lib/services/chat.ts b/frontend/src/lib/services/chat.ts
index 6e13d6bf..7236327e 100644
--- a/frontend/src/lib/services/chat.ts
+++ b/frontend/src/lib/services/chat.ts
@@ -13,7 +13,7 @@ import {
 } from "../validation/schemas";
 import { validateFetchJson } from "../validation/validate";
 import { csrfHeader, extractApiErrorMessage, fetchWithCsrfRetry } from "./csrf";
-import { streamWithRetry } from "./streamRecovery";
+import { streamSse } from "./sse";
 
 export type { StreamStatus, StreamError, Citation };
 
@@ -52,17 +52,17 @@ export async function streamChat(
   onChunk: (chunk: string) => void,
   options: StreamChatOptions = {},
 ): Promise<void> {
-  return streamWithRetry(
+  return streamSse(
     "/api/chat/stream",
     { sessionId, latest: message },
     {
-      onChunk,
+      onText: onChunk,
       onStatus: options.onStatus,
       onError: options.onError,
       onCitations: options.onCitations,
-      signal: options.signal,
     },
     "chat.ts",
+    { signal: options.signal },
   );
 }
 
diff --git a/frontend/src/lib/services/guided.test.ts b/frontend/src/lib/services/guided.test.ts
index 42a4a36a..cba8f2ae 100644
--- a/frontend/src/lib/services/guided.test.ts
+++ b/frontend/src/lib/services/guided.test.ts
@@ -10,22 +10,27 @@ vi.mock("./sse", () => {
 
 import { streamGuidedChat, streamLessonContent } from "./guided";
 
-describe("streamGuidedChat recovery", () => {
+describe("streamGuidedChat", () => {
   beforeEach(() => {
     streamSseMock.mockReset();
     streamSseGetMock.mockReset();
   });
 
-  it("retries once for recoverable invalid stream errors before any chunk", async () => {
-    streamSseMock.mockRejectedValueOnce(new Error("OverflowException: malformed response frame"));
+  it("surfaces a recoverable stream failure without replaying the POST", async () => {
+    const streamFailure = {
+      message: "OverflowException: malformed response frame",
+      details: "Malformed response frame at byte 512",
+    };
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
-      callbacks.onText("Recovered guided response");
+      callbacks.onError?.(streamFailure);
+      throw new Error(streamFailure.message);
     });
 
     const onChunk = vi.fn();
     const onStatus = vi.fn();
     const onError = vi.fn();
     const onCitations = vi.fn();
+    const streamAbortController = new AbortController();
 
     await expect(
       streamGuidedChat("guided-session-1", "intro", "Teach me streams", {
@@ -33,26 +38,33 @@ describe("streamGuidedChat recovery", () => {
         onStatus,
         onError,
         onCitations,
+        signal: streamAbortController.signal,
       }),
-    ).resolves.toBeUndefined();
+    ).rejects.toThrow("OverflowException: malformed response frame");
 
-    expect(streamSseMock).toHaveBeenCalledTimes(2);
-    expect(onStatus).toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: "Temporary stream issue detected",
-      }),
-    );
-    expect(onStatus).toHaveBeenCalledWith(
+    expect(streamSseMock).toHaveBeenCalledTimes(1);
+    expect(streamSseMock).toHaveBeenCalledWith(
+      "/api/guided/stream",
+      { sessionId: "guided-session-1", slug: "intro", latest: "Teach me streams" },
       expect.objectContaining({
-        message: "Streaming recovered",
+        onText: onChunk,
+        onStatus,
+        onError,
+        onCitations,
       }),
+      "guided.ts",
+      { signal: streamAbortController.signal },
     );
-    expect(onChunk).toHaveBeenCalledWith("Recovered guided response");
-    expect(onError).not.toHaveBeenCalled();
+    expect(onStatus).not.toHaveBeenCalled();
+    expect(onChunk).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledWith(streamFailure);
   });
 
   it("does not retry for non-recoverable rate-limit errors", async () => {
-    streamSseMock.mockRejectedValueOnce(new Error("429 rate limit exceeded"));
+    streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
+      callbacks.onError?.({ message: "429 rate limit exceeded" });
+      throw new Error("429 rate limit exceeded");
+    });
 
     const onChunk = vi.fn();
     const onStatus = vi.fn();
@@ -87,6 +99,7 @@ describe("streamGuidedChat recovery", () => {
         retryable: false,
         stage: "stream",
       });
+      callbacks.onError?.({ message: "Provider stream unavailable" });
       throw new Error("Provider stream unavailable");
     });
 
diff --git a/frontend/src/lib/services/guided.ts b/frontend/src/lib/services/guided.ts
index f9be3b86..77ae7931 100644
--- a/frontend/src/lib/services/guided.ts
+++ b/frontend/src/lib/services/guided.ts
@@ -17,8 +17,7 @@ import {
 } from "../validation/schemas";
 import { validateFetchJson } from "../validation/validate";
 import { fetchCitationsByEndpoint, type CitationFetchResult } from "./chat";
-import { streamSseGet } from "./sse";
-import { streamWithRetry } from "./streamRecovery";
+import { streamSse, streamSseGet } from "./sse";
 
 export type { StreamStatus, GuidedLesson, LessonContentResponse };
 
@@ -144,16 +143,16 @@ export async function streamGuidedChat(
   message: string,
   callbacks: GuidedStreamCallbacks,
 ): Promise<void> {
-  return streamWithRetry(
+  return streamSse(
     "/api/guided/stream",
     { sessionId, slug, latest: message },
     {
-      onChunk: callbacks.onChunk,
+      onText: callbacks.onChunk,
       onStatus: callbacks.onStatus,
       onError: callbacks.onError,
       onCitations: callbacks.onCitations,
-      signal: callbacks.signal,
     },
     "guided.ts",
+    { signal: callbacks.signal },
   );
 }
diff --git a/frontend/src/lib/services/streamRecovery.test.ts b/frontend/src/lib/services/streamRecovery.test.ts
deleted file mode 100644
index 0e78d958..00000000
--- a/frontend/src/lib/services/streamRecovery.test.ts
+++ /dev/null
@@ -1,166 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildStreamRecoverySucceededStatus,
-  buildStreamRetryStatus,
-  resolveStreamRecoveryRetryCount,
-  shouldRetryStreamRequest,
-  StreamFailureError,
-  toStreamError,
-  toStreamFailureException,
-} from "./streamRecovery";
-
-describe("streamRecovery", () => {
-  it("allows one retry for overflow failures before any chunk is rendered", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("OverflowException while decoding response"),
-      null,
-      null,
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(true);
-  });
-
-  it("refuses retry after content has started streaming", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("OverflowException while decoding response"),
-      null,
-      null,
-      true,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(false);
-  });
-
-  it("refuses retry for non-recoverable quota errors", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("HTTP 429 rate limit exceeded"),
-      null,
-      null,
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(false);
-  });
-
-  it("builds a user-visible retry status message", () => {
-    const retryStatus = buildStreamRetryStatus(1, 1);
-
-    expect(retryStatus.message).toBe("Temporary stream issue detected");
-    expect(retryStatus.details).toContain("Retrying your request (1/1)");
-  });
-
-  it("builds a user-visible recovery status message after retry succeeds", () => {
-    const recoveryStatus = buildStreamRecoverySucceededStatus(1);
-
-    expect(recoveryStatus.message).toBe("Streaming recovered");
-    expect(recoveryStatus.details).toContain("Recovered after retry (1)");
-  });
-
-  it("maps thrown errors into StreamError shape", () => {
-    const mappedStreamError = toStreamError(new Error("OverflowException"), null);
-
-    expect(mappedStreamError).toEqual({ message: "OverflowException" });
-  });
-
-  it("retries once for recoverable network failures before any chunk is rendered", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("TypeError: Failed to fetch"),
-      null,
-      null,
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(true);
-  });
-
-  it("respects backend retry metadata when stage is stream", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("Some fatal backend error"),
-      null,
-      {
-        message: "Provider fallback succeeded",
-        retryable: true,
-        stage: "stream",
-      },
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(true);
-  });
-
-  it("retries a generic terminal stream error when the backend marks it retryable", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("Streaming error"),
-      {
-        message: "Streaming error",
-        code: "stream.provider.retryable-error",
-        retryable: true,
-        stage: "stream",
-      },
-      null,
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(true);
-  });
-
-  it("refuses retry when a terminal error overrides an earlier retryable status", () => {
-    const retryDecision = shouldRetryStreamRequest(
-      new Error("Streaming error"),
-      {
-        message: "Streaming error",
-        code: "stream.provider.fatal-error",
-        retryable: false,
-        stage: "stream",
-      },
-      {
-        message: "Provider fallback succeeded",
-        retryable: true,
-        stage: "stream",
-      },
-      false,
-      0,
-      1,
-    );
-
-    expect(retryDecision).toBe(false);
-  });
-
-  it("preserves stream error details in thrown stream failure exception", () => {
-    const streamFailureException = toStreamFailureException(new Error("Transport failed"), {
-      message: "OverflowException",
-      details: "Malformed response frame at byte 512",
-    });
-
-    expect(streamFailureException).toBeInstanceOf(StreamFailureError);
-    expect(streamFailureException.message).toBe("OverflowException");
-    expect(streamFailureException.details).toBe("Malformed response frame at byte 512");
-  });
-
-  it("uses default retry count for missing config", () => {
-    expect(resolveStreamRecoveryRetryCount(undefined)).toBe(1);
-  });
-
-  it("clamps configured retry count into safe range", () => {
-    expect(resolveStreamRecoveryRetryCount(-1)).toBe(0);
-    expect(resolveStreamRecoveryRetryCount(9)).toBe(3);
-  });
-
-  it("falls back to default retry count for non-numeric config", () => {
-    expect(resolveStreamRecoveryRetryCount("abc")).toBe(1);
-    expect(resolveStreamRecoveryRetryCount("")).toBe(1);
-  });
-});
diff --git a/frontend/src/lib/services/streamRecovery.ts b/frontend/src/lib/services/streamRecovery.ts
deleted file mode 100644
index 91257c43..00000000
--- a/frontend/src/lib/services/streamRecovery.ts
+++ /dev/null
@@ -1,289 +0,0 @@
-import type { StreamError, StreamStatus, Citation } from "../validation/schemas";
-import { streamSse } from "./sse";
-
-const GENERIC_STREAM_FAILURE_MESSAGE = "Streaming request failed";
-
-/**
- * Error subclass carrying structured SSE stream failure details.
- * Replaces unsafe `as` casts that monkey-patched `details` onto plain Error objects.
- */
-export class StreamFailureError extends Error {
-  readonly details?: string;
-
-  constructor(message: string, details?: string) {
-    super(message);
-    this.name = "StreamFailureError";
-    this.details = details;
-  }
-}
-
-const RECOVERABLE_STREAM_ERROR_PATTERNS = [
-  /overflowexception/i,
-  /invalid\s+(stream|response)/i,
-  /malformed\s+(stream|response|json)/i,
-  /sseexception/i,
-  /unexpected end of json input/i,
-  /failed to fetch/i,
-  /networkerror/i,
-  /connection (reset|closed|refused)/i,
-  /socket hang up/i,
-  /\btimeout\b/i,
-  /\btimed out\b/i,
-  /\bhttp\s*5\d{2}\b/i,
-  /\b5\d{2}\s+(internal|bad gateway|service unavailable|gateway timeout)\b/i,
-];
-
-const NON_RECOVERABLE_STREAM_ERROR_PATTERNS = [
-  /rate limit/i,
-  /\b429\b/,
-  /\b401\b/,
-  /\b403\b/,
-  /providers unavailable/i,
-];
-const ABORT_STREAM_ERROR_PATTERNS = [/aborterror/i, /\baborted\b/i, /\bcancelled\b/i];
-
-const DEFAULT_STREAM_RECOVERY_RETRY_COUNT = 1;
-const MIN_STREAM_RECOVERY_RETRY_COUNT = 0;
-const MAX_STREAM_RECOVERY_RETRY_COUNT = 3;
-
-export const MAX_STREAM_RECOVERY_RETRIES = resolveStreamRecoveryRetryCount(
-  import.meta.env.VITE_STREAM_RECOVERY_MAX_RETRIES,
-);
-
-/**
- * Decides whether a stream request should be retried for a likely recoverable provider response issue.
- *
- * The retry gate is intentionally strict:
- * - bounded retries via MAX_STREAM_RECOVERY_RETRIES,
- * - only before any assistant chunk has been rendered,
- * - terminal backend metadata takes precedence over earlier status events,
- * - unstructured failures require a known recoverable signature.
- */
-export function shouldRetryStreamRequest(
-  streamFailure: unknown,
-  streamErrorEvent: StreamError | null,
-  latestStreamStatus: StreamStatus | null,
-  hasStreamedAnyChunk: boolean,
-  attemptedRetries: number,
-  maxRecoveryRetries: number,
-): boolean {
-  if (hasStreamedAnyChunk) {
-    return false;
-  }
-  if (attemptedRetries >= maxRecoveryRetries) {
-    return false;
-  }
-  if (typeof streamErrorEvent?.retryable === "boolean") {
-    return streamErrorEvent.retryable;
-  }
-  if (latestStreamStatus?.stage === "stream" && latestStreamStatus.retryable === false) {
-    return false;
-  }
-  if (latestStreamStatus?.stage === "stream" && latestStreamStatus.retryable === true) {
-    return true;
-  }
-
-  const failureDescription = describeStreamFailure(streamFailure, streamErrorEvent);
-  if (ABORT_STREAM_ERROR_PATTERNS.some((pattern) => pattern.test(failureDescription))) {
-    return false;
-  }
-  if (NON_RECOVERABLE_STREAM_ERROR_PATTERNS.some((pattern) => pattern.test(failureDescription))) {
-    return false;
-  }
-  return RECOVERABLE_STREAM_ERROR_PATTERNS.some((pattern) => pattern.test(failureDescription));
-}
-
-/**
- * Shows users that the client detected a transient stream fault and is retrying automatically.
- */
-export function buildStreamRetryStatus(
-  nextAttemptNumber: number,
-  maxRecoveryRetries: number,
-): StreamStatus {
-  return {
-    message: "Temporary stream issue detected",
-    details: `The API response or network stream was temporarily invalid. Retrying your request (${nextAttemptNumber}/${maxRecoveryRetries}).`,
-  };
-}
-
-/**
- * Reassures users that the retry path succeeded and normal streaming has resumed.
- */
-export function buildStreamRecoverySucceededStatus(recoveryAttemptCount: number): StreamStatus {
-  return {
-    message: "Streaming recovered",
-    details: `Recovered after retry (${recoveryAttemptCount}). Continuing your response.`,
-  };
-}
-
-/**
- * Converts thrown stream failures into the canonical StreamError shape used by UI components.
- */
-export function toStreamError(
-  streamFailure: unknown,
-  streamErrorEvent: StreamError | null,
-): StreamError {
-  if (streamErrorEvent) {
-    return streamErrorEvent;
-  }
-  if (streamFailure instanceof Error) {
-    return { message: streamFailure.message };
-  }
-  return { message: GENERIC_STREAM_FAILURE_MESSAGE };
-}
-
-/**
- * Converts stream failures into a typed StreamFailureError that preserves structured details.
- */
-export function toStreamFailureException(
-  streamFailure: unknown,
-  streamErrorEvent: StreamError | null,
-): StreamFailureError {
-  const mappedStreamError = toStreamError(streamFailure, streamErrorEvent);
-  return new StreamFailureError(mappedStreamError.message, mappedStreamError.details ?? undefined);
-}
-
-export function resolveStreamRecoveryRetryCount(rawRetrySetting: unknown): number {
-  if (rawRetrySetting === null || rawRetrySetting === undefined || rawRetrySetting === "") {
-    return DEFAULT_STREAM_RECOVERY_RETRY_COUNT;
-  }
-
-  const parsedRetryCount = Number(rawRetrySetting);
-  if (!Number.isInteger(parsedRetryCount)) {
-    return DEFAULT_STREAM_RECOVERY_RETRY_COUNT;
-  }
-  if (parsedRetryCount < MIN_STREAM_RECOVERY_RETRY_COUNT) {
-    return MIN_STREAM_RECOVERY_RETRY_COUNT;
-  }
-  if (parsedRetryCount > MAX_STREAM_RECOVERY_RETRY_COUNT) {
-    return MAX_STREAM_RECOVERY_RETRY_COUNT;
-  }
-  return parsedRetryCount;
-}
-
-/** Callbacks for the stream-with-retry wrapper. */
-export interface StreamWithRetryCallbacks {
-  onChunk: (chunk: string) => void;
-  onStatus?: (status: StreamStatus) => void;
-  onError?: (error: StreamError) => void;
-  onCitations?: (citations: Citation[]) => void;
-  signal?: AbortSignal;
-}
-
-/**
- * Streams an SSE endpoint with automatic retry on recoverable failures.
- * Retries only before the first assistant chunk is emitted to the UI.
- */
-export async function streamWithRetry(
-  endpoint: string,
-  body: object,
-  callbacks: StreamWithRetryCallbacks,
-  sourceLabel: string,
-): Promise<void> {
-  const { onChunk, onStatus, onError, onCitations, signal } = callbacks;
-  let attemptedRecoveryRetries = 0;
-  let hasPendingRecoverySuccessNotice = false;
-
-  while (true) {
-    let hasStreamedAnyChunk = false;
-    let streamErrorEvent: StreamError | null = null;
-    let latestStreamStatus: StreamStatus | null = null;
-
-    try {
-      await streamSse(
-        endpoint,
-        body,
-        {
-          onText: (chunk) => {
-            hasStreamedAnyChunk = true;
-            if (hasPendingRecoverySuccessNotice) {
-              onStatus?.(buildStreamRecoverySucceededStatus(attemptedRecoveryRetries));
-              hasPendingRecoverySuccessNotice = false;
-            }
-            onChunk(chunk);
-          },
-          onStatus: (status) => {
-            latestStreamStatus = status;
-            onStatus?.(status);
-          },
-          onError: (streamError) => {
-            streamErrorEvent = streamError;
-          },
-          onCitations,
-        },
-        sourceLabel,
-        { signal },
-      );
-      return;
-    } catch (streamFailure) {
-      if (
-        shouldRetryStreamRequest(
-          streamFailure,
-          streamErrorEvent,
-          latestStreamStatus,
-          hasStreamedAnyChunk,
-          attemptedRecoveryRetries,
-          MAX_STREAM_RECOVERY_RETRIES,
-        )
-      ) {
-        attemptedRecoveryRetries++;
-        hasPendingRecoverySuccessNotice = true;
-        onStatus?.(buildStreamRetryStatus(attemptedRecoveryRetries, MAX_STREAM_RECOVERY_RETRIES));
-        continue;
-      }
-      const mappedStreamError = toStreamError(streamFailure, streamErrorEvent);
-      onError?.(mappedStreamError);
-      throw toStreamFailureException(streamFailure, streamErrorEvent);
-    }
-  }
-}
-
-function describeStreamFailure(
-  streamFailure: unknown,
-  streamErrorEvent: StreamError | null,
-): string {
-  const diagnosticTokens: string[] = [];
-  if (streamErrorEvent?.message) {
-    diagnosticTokens.push(streamErrorEvent.message);
-  }
-  if (streamErrorEvent?.details) {
-    diagnosticTokens.push(streamErrorEvent.details);
-  }
-  if (streamErrorEvent?.code) {
-    diagnosticTokens.push(streamErrorEvent.code);
-  }
-  if (streamFailure instanceof Error) {
-    diagnosticTokens.push(streamFailure.message);
-    if ("details" in streamFailure && typeof streamFailure.details === "string") {
-      diagnosticTokens.push(streamFailure.details);
-    }
-  } else if (streamFailure !== null && streamFailure !== undefined) {
-    diagnosticTokens.push(formatUnknownDiagnostic(streamFailure));
-  }
-  return diagnosticTokens.join(" ").trim();
-}
-
-function formatUnknownDiagnostic(value: unknown): string {
-  if (typeof value === "string") {
-    return value;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (typeof value === "bigint") {
-    return value.toString();
-  }
-  if (typeof value === "symbol") {
-    return value.description ?? "Symbol";
-  }
-  if (typeof value === "function") {
-    return value.name ? `[function ${value.name}]` : "[function]";
-  }
-
-  try {
-    const json = JSON.stringify(value);
-    return json === undefined ? "" : json;
-  } catch {
-    return Object.prototype.toString.call(value);
-  }
-}
diff --git a/src/main/java/com/williamcallahan/javachat/service/ChatMemoryService.java b/src/main/java/com/williamcallahan/javachat/service/ChatMemoryService.java
index 1c0207a5..bfd8abd5 100644
--- a/src/main/java/com/williamcallahan/javachat/service/ChatMemoryService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/ChatMemoryService.java
@@ -38,29 +38,19 @@ public List<Message> getHistory(String sessionId) {
     }
 
     /**
-     * Adds a user message to the session history and turn list.
+     * Commits one completed user/assistant exchange atomically.
      *
-     * @param sessionId session identifier
-     * @param text message text
-     */
-    public void addUser(String sessionId, String text) {
-        Objects.requireNonNull(sessionId, REQUIRE_SESSION_ID);
-        SessionConversation sessionConversation =
-                sessionConversations.computeIfAbsent(sessionId, _ -> new SessionConversation());
-        sessionConversation.addUserMessage(text);
-    }
-
-    /**
-     * Adds an assistant message to the session history and turn list.
+     * <p>Failed or cancelled streams never leave an unmatched user turn in memory.</p>
      *
      * @param sessionId session identifier
-     * @param text message text
+     * @param userText user message text
+     * @param assistantText assistant message text
      */
-    public void addAssistant(String sessionId, String text) {
+    public void addExchange(String sessionId, String userText, String assistantText) {
         Objects.requireNonNull(sessionId, REQUIRE_SESSION_ID);
         SessionConversation sessionConversation =
                 sessionConversations.computeIfAbsent(sessionId, _ -> new SessionConversation());
-        sessionConversation.addAssistantMessage(text);
+        sessionConversation.addExchange(userText, assistantText);
     }
 
     /**
@@ -114,14 +104,11 @@ private static final class SessionConversation {
         private final List<Message> historyMessages = new ArrayList<>();
         private final List<ChatTurn> turnHistory = new ArrayList<>();
 
-        synchronized void addUserMessage(String text) {
-            historyMessages.add(new UserMessage(text));
-            turnHistory.add(new ChatTurn("user", text));
-        }
-
-        synchronized void addAssistantMessage(String text) {
-            historyMessages.add(new AssistantMessage(text));
-            turnHistory.add(new ChatTurn("assistant", text));
+        synchronized void addExchange(String userText, String assistantText) {
+            historyMessages.add(new UserMessage(userText));
+            turnHistory.add(new ChatTurn("user", userText));
+            historyMessages.add(new AssistantMessage(assistantText));
+            turnHistory.add(new ChatTurn("assistant", assistantText));
         }
 
         synchronized List<Message> historySnapshot() {
diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
index 2b1e06d5..1993e576 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
@@ -168,20 +168,12 @@ public Mono<StreamingResult> streamResponse(StructuredPrompt structuredPrompt, d
                     // Routing selects two candidates, so one pre-text fallback signal is sufficient.
                     Sinks.Many<StreamingNotice> noticeSink =
                             Sinks.many().replay().limit(1);
-                    Sinks.One<RateLimitService.ApiProvider> providerChangeSink = Sinks.one();
                     StreamingAttemptContext attemptContext =
-                            StreamingAttemptContext.first(availableProviders, noticeSink, providerChangeSink);
+                            StreamingAttemptContext.first(availableProviders, noticeSink);
                     Flux<String> contentFlux = executeStreamingWithPreTextRetry(
                                     structuredPrompt, temperature, attemptContext)
-                            .doFinally(ignoredSignalType -> {
-                                noticeSink.tryEmitComplete();
-                                providerChangeSink.tryEmitEmpty();
-                            });
-                    return Mono.just(new StreamingResult(
-                            contentFlux,
-                            initialProvider.provider(),
-                            providerChangeSink.asMono().flux(),
-                            noticeSink.asFlux()));
+                            .doFinally(ignoredSignalType -> noticeSink.tryEmitComplete());
+                    return Mono.just(new StreamingResult(contentFlux, initialProvider.provider(), noticeSink.asFlux()));
                 })
                 .subscribeOn(Schedulers.boundedElastic());
     }
@@ -379,7 +371,6 @@ private Flux<String> executeStreamingWithPreTextRetry(
                             nextAttempt.maxAttempts(),
                             streamingFailure.getClass().getSimpleName());
 
-                    emitProviderChange(attemptContext.providerChangeSink(), retryProvider.provider());
                     emitStreamingNotice(
                             attemptContext.noticeSink(),
                             StreamingNotice.builder(
@@ -495,15 +486,4 @@ private void emitStreamingNotice(Sinks.Many<StreamingNotice> noticeSink, Streami
             log.debug("Failed to emit streaming notice (emitResult={})", emitResult);
         }
     }
-
-    private void emitProviderChange(
-            Sinks.One<RateLimitService.ApiProvider> providerChangeSink, RateLimitService.ApiProvider fallbackProvider) {
-        Sinks.EmitResult emitResult = providerChangeSink.tryEmitValue(fallbackProvider);
-        if (emitResult.isFailure()) {
-            log.debug(
-                    "Failed to emit fallback provider change (providerId={}, emitResult={})",
-                    fallbackProvider.ordinal(),
-                    emitResult);
-        }
-    }
 }
diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
index bced68f8..e94e3651 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
@@ -174,7 +174,38 @@ public boolean isStreamingFallbackEligible(Throwable throwable) {
      * @return true when the failure appears transient and retryable
      */
     public boolean isRecoverableStreamingFailure(Throwable throwable) {
-        return throwable != null && isStreamingFallbackEligible(throwable);
+        if (throwable == null || isCallerCancellation(throwable)) {
+            return false;
+        }
+        if (throwable instanceof UnauthorizedException
+                || throwable instanceof PermissionDeniedException
+                || throwable instanceof RateLimitException
+                || throwable instanceof NotFoundException) {
+            return false;
+        }
+        if (throwable instanceof OpenAIIoException
+                || throwable instanceof SseException
+                || Exceptions.isOverflow(throwable)) {
+            return true;
+        }
+        if (throwable instanceof OpenAIServiceException serviceException) {
+            int statusCode = serviceException.statusCode();
+            return statusCode == HTTP_REQUEST_TIMEOUT
+                    || statusCode == HTTP_CONFLICT
+                    || statusCode >= HTTP_INTERNAL_SERVER_ERROR;
+        }
+        String exceptionMessage = throwable.getMessage();
+        if (exceptionMessage == null) {
+            return false;
+        }
+        String normalizedMessage = AsciiTextNormalizer.toLowerAscii(exceptionMessage);
+        return normalizedMessage.contains("invalid stream")
+                || normalizedMessage.contains("malformed")
+                || normalizedMessage.contains("unexpected end of json input")
+                || normalizedMessage.contains("timeout")
+                || normalizedMessage.contains("temporarily unavailable")
+                || normalizedMessage.contains("connection reset")
+                || normalizedMessage.contains("connection closed");
     }
 
     boolean shouldBackoffPrimary(Throwable throwable) {
diff --git a/src/main/java/com/williamcallahan/javachat/service/StreamingAttemptContext.java b/src/main/java/com/williamcallahan/javachat/service/StreamingAttemptContext.java
index 34367b1c..0bfc9557 100644
--- a/src/main/java/com/williamcallahan/javachat/service/StreamingAttemptContext.java
+++ b/src/main/java/com/williamcallahan/javachat/service/StreamingAttemptContext.java
@@ -8,14 +8,10 @@
  * Tracks bounded provider attempts during streaming before response text is emitted.
  */
 record StreamingAttemptContext(
-        List<OpenAiProviderCandidate> availableProviders,
-        int attemptIndex,
-        Sinks.Many<StreamingNotice> noticeSink,
-        Sinks.One<RateLimitService.ApiProvider> providerChangeSink) {
+        List<OpenAiProviderCandidate> availableProviders, int attemptIndex, Sinks.Many<StreamingNotice> noticeSink) {
     StreamingAttemptContext {
         Objects.requireNonNull(availableProviders, "availableProviders");
         Objects.requireNonNull(noticeSink, "noticeSink");
-        Objects.requireNonNull(providerChangeSink, "providerChangeSink");
         if (availableProviders.isEmpty()) {
             throw new IllegalArgumentException("availableProviders cannot be empty");
         }
@@ -27,10 +23,8 @@ record StreamingAttemptContext(
     }
 
     static StreamingAttemptContext first(
-            List<OpenAiProviderCandidate> availableProviders,
-            Sinks.Many<StreamingNotice> noticeSink,
-            Sinks.One<RateLimitService.ApiProvider> providerChangeSink) {
-        return new StreamingAttemptContext(availableProviders, 0, noticeSink, providerChangeSink);
+            List<OpenAiProviderCandidate> availableProviders, Sinks.Many<StreamingNotice> noticeSink) {
+        return new StreamingAttemptContext(availableProviders, 0, noticeSink);
     }
 
     OpenAiProviderCandidate currentProvider() {
@@ -54,7 +48,7 @@ StreamingAttemptContext withNextAttempt() {
             throw new IllegalStateException("streaming attempts are exhausted");
         }
 
-        return new StreamingAttemptContext(availableProviders, attemptIndex + 1, noticeSink, providerChangeSink);
+        return new StreamingAttemptContext(availableProviders, attemptIndex + 1, noticeSink);
     }
 
     private static int maximumAttemptsFor(List<OpenAiProviderCandidate> availableProviders) {
diff --git a/src/main/java/com/williamcallahan/javachat/service/StreamingResult.java b/src/main/java/com/williamcallahan/javachat/service/StreamingResult.java
index 8c2d18bd..dbab186c 100644
--- a/src/main/java/com/williamcallahan/javachat/service/StreamingResult.java
+++ b/src/main/java/com/williamcallahan/javachat/service/StreamingResult.java
@@ -7,14 +7,10 @@
  *
  * @param textChunks the streaming response flux
  * @param provider the initially selected LLM provider for this request
- * @param providerChanges providers selected for a retry after a pre-text fallback
  * @param notices runtime streaming notices (for example, pre-first-token provider failover)
  */
 public record StreamingResult(
-        Flux<String> textChunks,
-        RateLimitService.ApiProvider provider,
-        Flux<RateLimitService.ApiProvider> providerChanges,
-        Flux<StreamingNotice> notices) {
+        Flux<String> textChunks, RateLimitService.ApiProvider provider, Flux<StreamingNotice> notices) {
     /** Returns a user-friendly display name for the provider. */
     public String providerDisplayName() {
         return provider.getName();
diff --git a/src/main/java/com/williamcallahan/javachat/web/ChatController.java b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
index c099860a..9115b73e 100644
--- a/src/main/java/com/williamcallahan/javachat/web/ChatController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
@@ -173,11 +173,8 @@ public Flux<ServerSentEvent<String>> stream(
                                     statusEvents = statusEvents.concatWith(
                                             sseSupport.citationWarningStatusFlux(finalCitationWarning));
 
-                                    Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
+                                    Flux<ServerSentEvent<String>> runtimeStreamingEvents =
                                             sseSupport.streamingNoticeEvents(streamingResult.notices());
-                                    Flux<ServerSentEvent<String>> providerChangeEvents = streamingResult
-                                            .providerChanges()
-                                            .map(provider -> sseSupport.providerEvent(provider.getName()));
 
                                     // Wrap chunks in JSON to preserve whitespace
                                     Flux<ServerSentEvent<String>> dataEvents = dataStream.map(sseSupport::textEvent);
@@ -185,16 +182,12 @@ public Flux<ServerSentEvent<String>> stream(
                                     Flux<ServerSentEvent<String>> citationEvent =
                                             Flux.just(sseSupport.citationEvent(finalCitations));
 
-                                    // Subscribe to replayable fallback signals before the ref-counted data stream
-                                    // starts.
+                                    // Start replayable fallback protocol events before the ref-counted data stream
+                                    // so the provider and status notice arrive before fallback text.
                                     return Flux.concat(
                                             Flux.just(providerEvent),
                                             statusEvents,
-                                            Flux.merge(
-                                                    providerChangeEvents,
-                                                    runtimeStreamingStatusEvents,
-                                                    dataEvents,
-                                                    heartbeats),
+                                            Flux.merge(runtimeStreamingEvents, dataEvents, heartbeats),
                                             citationEvent);
                                 })
                                 .doOnComplete(() -> {
diff --git a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
index ea5b827b..db276d54 100644
--- a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
@@ -297,21 +297,15 @@ private Flux<ServerSentEvent<String>> streamGuidedResponse(String sessionId, Str
 
                                 Flux<ServerSentEvent<String>> statusEvents =
                                         sseSupport.citationWarningStatusFlux(finalCitationWarning);
-                                Flux<ServerSentEvent<String>> runtimeStreamingStatusEvents =
+                                Flux<ServerSentEvent<String>> runtimeStreamingEvents =
                                         sseSupport.streamingNoticeEvents(streamingResult.notices());
-                                Flux<ServerSentEvent<String>> providerChangeEvents = streamingResult
-                                        .providerChanges()
-                                        .map(provider -> sseSupport.providerEvent(provider.getName()));
 
-                                // Subscribe to replayable fallback signals before the ref-counted data stream starts.
+                                // Start replayable fallback protocol events before the ref-counted data stream so
+                                // the provider and status notice arrive before fallback text.
                                 return Flux.concat(
                                         Flux.just(providerEvent),
                                         statusEvents,
-                                        Flux.merge(
-                                                providerChangeEvents,
-                                                runtimeStreamingStatusEvents,
-                                                dataEvents,
-                                                heartbeats),
+                                        Flux.merge(runtimeStreamingEvents, dataEvents, heartbeats),
                                         citationEvent);
                             })
                             .doOnComplete(() -> chatMemory.addAssistant(sessionId, fullResponse.toString()));
diff --git a/src/main/java/com/williamcallahan/javachat/web/SseSupport.java b/src/main/java/com/williamcallahan/javachat/web/SseSupport.java
index 9af24ca0..8c7366ca 100644
--- a/src/main/java/com/williamcallahan/javachat/web/SseSupport.java
+++ b/src/main/java/com/williamcallahan/javachat/web/SseSupport.java
@@ -257,21 +257,33 @@ public ServerSentEvent<String> providerEvent(String providerName) {
     }
 
     /**
-     * Maps runtime streaming notices from the LLM provider into SSE status events.
+     * Projects runtime streaming notices into their SSE protocol events.
+     *
+     * <p>Provider-fallback notices emit the fallback provider before their status event. One
+     * subscription to the replayed notice flux owns both projections, while {@code concatMap}
+     * keeps each notice's protocol events ordered and non-interleaved.</p>
      *
      * @param notices flux of streaming notices from the provider
-     * @return flux of ServerSentEvents with structured status payloads
+     * @return flux of ordered ServerSentEvents with provider and status payloads
      */
     public Flux<ServerSentEvent<String>> streamingNoticeEvents(Flux<StreamingNotice> notices) {
-        return notices.map(notice -> statusEvent(SseEventPayload.builder(notice.summary())
-                .details(notice.diagnosticContext())
-                .code(notice.code())
-                .retryable(notice.retryable())
-                .provider(notice.provider())
-                .stage(notice.stage())
-                .attempt(notice.attempt())
-                .maxAttempts(notice.maxAttempts())
-                .build()));
+        return notices.concatMap(this::streamingNoticeEventSequence);
+    }
+
+    private Flux<ServerSentEvent<String>> streamingNoticeEventSequence(StreamingNotice streamingNotice) {
+        ServerSentEvent<String> noticeStatusEvent = statusEvent(SseEventPayload.builder(streamingNotice.summary())
+                .details(streamingNotice.diagnosticContext())
+                .code(streamingNotice.code())
+                .retryable(streamingNotice.retryable())
+                .provider(streamingNotice.provider())
+                .stage(streamingNotice.stage())
+                .attempt(streamingNotice.attempt())
+                .maxAttempts(streamingNotice.maxAttempts())
+                .build());
+        if (STATUS_CODE_STREAM_PROVIDER_FALLBACK.equals(streamingNotice.code())) {
+            return Flux.just(providerEvent(streamingNotice.provider()), noticeStatusEvent);
+        }
+        return Flux.just(noticeStatusEvent);
     }
 
     /**
diff --git a/src/test/java/com/williamcallahan/javachat/service/ChatMemoryServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/ChatMemoryServiceTest.java
index 80cd82fb..6c43df54 100644
--- a/src/test/java/com/williamcallahan/javachat/service/ChatMemoryServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/ChatMemoryServiceTest.java
@@ -28,29 +28,18 @@ void setUp() {
     }
 
     @Test
-    @DisplayName("Should store and retrieve user messages")
-    void shouldStoreAndRetrieveUserMessages() {
+    @DisplayName("Should store completed exchanges")
+    void shouldStoreCompletedExchanges() {
         String sessionId = "test-session";
-        chatMemoryService.addUser(sessionId, "What is Java?");
+        chatMemoryService.addExchange(sessionId, "What is Java?", "Java is a programming language.");
 
         List<Message> history = chatMemoryService.getHistory(sessionId);
 
-        assertEquals(1, history.size());
+        assertEquals(2, history.size());
         assertInstanceOf(UserMessage.class, history.get(0));
         assertEquals("What is Java?", ((UserMessage) history.get(0)).getText());
-    }
-
-    @Test
-    @DisplayName("Should store and retrieve assistant messages")
-    void shouldStoreAndRetrieveAssistantMessages() {
-        String sessionId = "test-session";
-        chatMemoryService.addAssistant(sessionId, "Java is a programming language.");
-
-        List<Message> history = chatMemoryService.getHistory(sessionId);
-
-        assertEquals(1, history.size());
-        assertInstanceOf(AssistantMessage.class, history.get(0));
-        assertEquals("Java is a programming language.", ((AssistantMessage) history.get(0)).getText());
+        assertInstanceOf(AssistantMessage.class, history.get(1));
+        assertEquals("Java is a programming language.", ((AssistantMessage) history.get(1)).getText());
     }
 
     @Test
@@ -58,10 +47,8 @@ void shouldStoreAndRetrieveAssistantMessages() {
     void shouldMaintainConversationOrder() {
         String sessionId = "test-session";
 
-        chatMemoryService.addUser(sessionId, "What is Java?");
-        chatMemoryService.addAssistant(sessionId, "Java is a programming language.");
-        chatMemoryService.addUser(sessionId, "Give me an example.");
-        chatMemoryService.addAssistant(sessionId, "Here is a Hello World example...");
+        chatMemoryService.addExchange(sessionId, "What is Java?", "Java is a programming language.");
+        chatMemoryService.addExchange(sessionId, "Give me an example.", "Here is a Hello World example...");
 
         List<Message> history = chatMemoryService.getHistory(sessionId);
 
@@ -86,8 +73,7 @@ void shouldReturnEmptyHistoryForUnknownSession() {
     @DisplayName("Should clear session history")
     void shouldClearSessionHistory() {
         String sessionId = "test-session";
-        chatMemoryService.addUser(sessionId, "Test message");
-        chatMemoryService.addAssistant(sessionId, "Test response");
+        chatMemoryService.addExchange(sessionId, "Test message", "Test response");
 
         chatMemoryService.clear(sessionId);
 
@@ -99,14 +85,14 @@ void shouldClearSessionHistory() {
     @Test
     @DisplayName("Should isolate sessions from each other")
     void shouldIsolateSessions() {
-        chatMemoryService.addUser("session-1", "Message for session 1");
-        chatMemoryService.addUser("session-2", "Message for session 2");
+        chatMemoryService.addExchange("session-1", "Message for session 1", "Response for session 1");
+        chatMemoryService.addExchange("session-2", "Message for session 2", "Response for session 2");
 
         List<Message> history1 = chatMemoryService.getHistory("session-1");
         List<Message> history2 = chatMemoryService.getHistory("session-2");
 
-        assertEquals(1, history1.size());
-        assertEquals(1, history2.size());
+        assertEquals(2, history1.size());
+        assertEquals(2, history2.size());
         assertEquals("Message for session 1", ((UserMessage) history1.get(0)).getText());
         assertEquals("Message for session 2", ((UserMessage) history2.get(0)).getText());
     }
@@ -115,23 +101,22 @@ void shouldIsolateSessions() {
     @DisplayName("Should return snapshot that is safe to iterate")
     void shouldReturnSnapshotSafeToIterate() {
         String sessionId = "test-session";
-        chatMemoryService.addUser(sessionId, "First message");
+        chatMemoryService.addExchange(sessionId, "First message", "First response");
 
         List<Message> history = chatMemoryService.getHistory(sessionId);
 
         // Modify the original session after getting history
-        chatMemoryService.addUser(sessionId, "Second message");
+        chatMemoryService.addExchange(sessionId, "Second message", "Second response");
 
         // The snapshot should not be affected
-        assertEquals(1, history.size());
+        assertEquals(2, history.size());
     }
 
     @Test
     @DisplayName("Should track turns alongside messages")
     void shouldTrackTurnsAlongsideMessages() {
         String sessionId = "test-session";
-        chatMemoryService.addUser(sessionId, "User question");
-        chatMemoryService.addAssistant(sessionId, "Assistant answer");
+        chatMemoryService.addExchange(sessionId, "User question", "Assistant answer");
 
         var turns = chatMemoryService.getTurns(sessionId);
 
@@ -156,7 +141,7 @@ void shouldKeepHistoryAndTurnsAlignedUnderConcurrency() throws InterruptedExcept
             workerPool.execute(() -> {
                 try {
                     startSignal.await();
-                    chatMemoryService.addUser(sessionId, "message-" + messageIndex);
+                    chatMemoryService.addExchange(sessionId, "message-" + messageIndex, "response-" + messageIndex);
                 } catch (InterruptedException interruption) {
                     Thread.currentThread().interrupt();
                 } finally {
@@ -172,10 +157,10 @@ void shouldKeepHistoryAndTurnsAlignedUnderConcurrency() throws InterruptedExcept
 
         List<Message> history = chatMemoryService.getHistory(sessionId);
         var turns = chatMemoryService.getTurns(sessionId);
-        assertEquals(workerCount, history.size());
-        assertEquals(workerCount, turns.size());
-        for (int messageIndex = 0; messageIndex < workerCount; messageIndex++) {
-            String historyText = ((UserMessage) history.get(messageIndex)).getText();
+        assertEquals(workerCount * 2, history.size());
+        assertEquals(workerCount * 2, turns.size());
+        for (int messageIndex = 0; messageIndex < workerCount * 2; messageIndex++) {
+            String historyText = history.get(messageIndex).getText();
             String turnText = turns.get(messageIndex).getText();
             assertEquals(historyText, turnText);
         }
diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
index 5187e786..e4afed13 100644
--- a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
@@ -23,6 +23,7 @@
 import com.openai.errors.InternalServerException;
 import com.openai.errors.NotFoundException;
 import com.openai.errors.OpenAIIoException;
+import com.openai.errors.PermissionDeniedException;
 import com.openai.errors.RateLimitException;
 import com.openai.errors.UnauthorizedException;
 import com.openai.models.ErrorObject;
@@ -86,15 +87,16 @@ void stopCapturingServiceLogs() {
 
     private OpenAiProviderRoutingService createRoutingService() {
         RateLimitService rateLimitService = mock(RateLimitService.class);
-        return new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        return new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
     }
 
     private OpenAIStreamingService createStreamingService() {
         RateLimitService rateLimitService = mock(RateLimitService.class);
         OpenAiRequestFactory requestFactory =
                 new OpenAiRequestFactory(new Chunker(), new PromptTruncator(), "gpt-5.2", "gpt-5", "");
-        OpenAiProviderRoutingService providerRoutingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        OpenAiProviderRoutingService providerRoutingService = new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
         return new OpenAIStreamingService(
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
     }
@@ -121,7 +123,8 @@ void callerCancellationKeepsConfiguredPrimaryProviderEligible() {
                 .thenReturn(true);
         when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
                 .thenReturn(true);
-        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(rateLimitService, 600, "openai");
+        OpenAiProviderRoutingService routingService =
+                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
         OpenAIClient openAiClient = mock(OpenAIClient.class);
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
         InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
@@ -183,21 +186,38 @@ void recoverableStreamingFailureTreatsValidationErrorsAsNonRetryable() {
     }
 
     @Test
-    void recoverableStreamingFailureTreatsNotFoundAsRetryable() {
+    void recoverableStreamingFailureTreatsNotFoundAsNonRetryable() {
         OpenAIStreamingService streamingService = createStreamingService();
         Headers headers = Headers.builder().build();
         NotFoundException notFoundException =
                 NotFoundException.builder().headers(headers).build();
-        assertTrue(streamingService.isRecoverableStreamingFailure(notFoundException));
+        assertFalse(streamingService.isRecoverableStreamingFailure(notFoundException));
+    }
+
+    @Test
+    void recoverableStreamingFailureRejectsAuthenticationAuthorizationAndRateLimitFailures() {
+        OpenAIStreamingService streamingService = createStreamingService();
+        Headers headers = Headers.builder().build();
+
+        assertFalse(streamingService.isRecoverableStreamingFailure(
+                UnauthorizedException.builder().headers(headers).build()));
+        assertFalse(streamingService.isRecoverableStreamingFailure(
+                PermissionDeniedException.builder().headers(headers).build()));
+        assertFalse(streamingService.isRecoverableStreamingFailure(
+                RateLimitException.builder().headers(headers).build()));
     }
 
     @Test
     void recoverableStreamingFailureUnwrapsNestedTerminalContext() {
         OpenAIStreamingService streamingService = createStreamingService();
-        NotFoundException notFoundException =
-                NotFoundException.builder().headers(Headers.builder().build()).build();
+        InternalServerException internalServerException = InternalServerException.builder()
+                .statusCode(503)
+                .headers(Headers.builder().build())
+                .build();
         OpenAiStreamingFailureException terminalFailure = OpenAiStreamingFailureException.terminalAndLog(
-                notFoundException, new StreamingFailureReporter.TerminalAttempt("openai", "gpt-5.2", 1, 1, false));
+                internalServerException,
+                new StreamingFailureReporter.TerminalAttempt(
+                        RateLimitService.ApiProvider.OPENAI.getName(), "gpt-5.2", 1, 1, false));
 
         assertTrue(streamingService.isRecoverableStreamingFailure(
                 new IllegalStateException("reactor boundary", terminalFailure)));
@@ -211,8 +231,8 @@ void subscribedTerminalStreamFailureLogsOneBoundedAlert() {
                 .thenReturn(true);
         OpenAiRequestFactory requestFactory =
                 new OpenAiRequestFactory(new Chunker(), new PromptTruncator(), "gpt-5.2", "gpt-5", "");
-        OpenAiProviderRoutingService providerRoutingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        OpenAiProviderRoutingService providerRoutingService = new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
         OpenAIStreamingService streamingService = new OpenAIStreamingService(
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
@@ -261,8 +281,8 @@ void emptyTextDeltaDoesNotRepeatTheOnlyProvider() {
                 .thenReturn(true);
         OpenAiRequestFactory requestFactory =
                 new OpenAiRequestFactory(new Chunker(), new PromptTruncator(), "gpt-5.2", "gpt-5", "");
-        OpenAiProviderRoutingService providerRoutingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        OpenAiProviderRoutingService providerRoutingService = new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
         OpenAIStreamingService streamingService = new OpenAIStreamingService(
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
@@ -308,8 +328,8 @@ void preTextFailureMovesToDistinctSecondProviderAndPublishesReplayableFallbackSi
                 .thenReturn(true);
         OpenAiRequestFactory requestFactory =
                 new OpenAiRequestFactory(new Chunker(), new PromptTruncator(), "gpt-5.2", "gpt-5", "");
-        OpenAiProviderRoutingService providerRoutingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        OpenAiProviderRoutingService providerRoutingService = new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
         OpenAIStreamingService streamingService = new OpenAIStreamingService(
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
@@ -344,14 +364,10 @@ void preTextFailureMovesToDistinctSecondProviderAndPublishesReplayableFallbackSi
                 .expectNext("second provider text")
                 .verifyComplete();
 
-        StepVerifier.create(streamingResult.providerChanges())
-                .expectNext(RateLimitService.ApiProvider.OPENAI)
-                .verifyComplete();
-
         StepVerifier.create(streamingResult.notices())
                 .assertNext(fallbackNotice -> {
                     assertEquals(SseConstants.STATUS_CODE_STREAM_PROVIDER_FALLBACK, fallbackNotice.code());
-                    assertEquals("openai", fallbackNotice.provider());
+                    assertEquals(RateLimitService.ApiProvider.OPENAI.getName(), fallbackNotice.provider());
                     assertEquals(SseConstants.STATUS_STAGE_STREAM, fallbackNotice.stage());
                     assertEquals(2, fallbackNotice.attempt());
                     assertEquals(2, fallbackNotice.maxAttempts());
@@ -370,8 +386,8 @@ void nonEmptyTextDeltaDisablesPreTextRetry() {
                 .thenReturn(true);
         OpenAiRequestFactory requestFactory =
                 new OpenAiRequestFactory(new Chunker(), new PromptTruncator(), "gpt-5.2", "gpt-5", "");
-        OpenAiProviderRoutingService providerRoutingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, "github_models");
+        OpenAiProviderRoutingService providerRoutingService = new OpenAiProviderRoutingService(
+                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
         OpenAIStreamingService streamingService = new OpenAIStreamingService(
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
@@ -413,7 +429,8 @@ void primaryBackoffDoesNotHideOnlyConfiguredProvider() {
         RateLimitService rateLimitService = mock(RateLimitService.class);
         when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
                 .thenReturn(true);
-        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(rateLimitService, 600, "openai");
+        OpenAiProviderRoutingService routingService =
+                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
         OpenAIClient openAiClient = mock(OpenAIClient.class);
 
         routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
@@ -433,7 +450,8 @@ void primaryBackoffUsesConfiguredAlternateProviderWhenAvailable() {
                 .thenReturn(true);
         when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
                 .thenReturn(true);
-        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(rateLimitService, 600, "openai");
+        OpenAiProviderRoutingService routingService =
+                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
         OpenAIClient openAiClient = mock(OpenAIClient.class);
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
 
diff --git a/src/test/java/com/williamcallahan/javachat/service/StreamingAttemptContextTest.java b/src/test/java/com/williamcallahan/javachat/service/StreamingAttemptContextTest.java
index 9729b694..bac718db 100644
--- a/src/test/java/com/williamcallahan/javachat/service/StreamingAttemptContextTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/StreamingAttemptContextTest.java
@@ -20,8 +20,7 @@ class StreamingAttemptContextTest {
     @Test
     void singleProviderIsAttemptedExactlyOnce() {
         OpenAiProviderCandidate onlyProvider = provider(RateLimitService.ApiProvider.OPENAI);
-        StreamingAttemptContext firstAttempt =
-                StreamingAttemptContext.first(List.of(onlyProvider), noticeSink(), providerChangeSink());
+        StreamingAttemptContext firstAttempt = StreamingAttemptContext.first(List.of(onlyProvider), noticeSink());
 
         assertAttempt(firstAttempt, onlyProvider, 1, SINGLE_PROVIDER_ATTEMPT_COUNT, false);
         assertThrows(IllegalStateException.class, firstAttempt::withNextAttempt);
@@ -31,8 +30,8 @@ void singleProviderIsAttemptedExactlyOnce() {
     void multipleProvidersAreAttemptedExactlyOnceEach() {
         OpenAiProviderCandidate primaryProvider = provider(RateLimitService.ApiProvider.OPENAI);
         OpenAiProviderCandidate secondaryProvider = provider(RateLimitService.ApiProvider.GITHUB_MODELS);
-        StreamingAttemptContext firstAttempt = StreamingAttemptContext.first(
-                List.of(primaryProvider, secondaryProvider), noticeSink(), providerChangeSink());
+        StreamingAttemptContext firstAttempt =
+                StreamingAttemptContext.first(List.of(primaryProvider, secondaryProvider), noticeSink());
 
         assertAttempt(firstAttempt, primaryProvider, 1, DISTINCT_PROVIDER_ATTEMPT_COUNT, true);
 
@@ -50,10 +49,6 @@ private static Sinks.Many<StreamingNotice> noticeSink() {
         return Sinks.many().multicast().onBackpressureBuffer();
     }
 
-    private static Sinks.One<RateLimitService.ApiProvider> providerChangeSink() {
-        return Sinks.one();
-    }
-
     private static void assertAttempt(
             StreamingAttemptContext attemptContext,
             OpenAiProviderCandidate expectedProvider,
diff --git a/src/test/java/com/williamcallahan/javachat/web/ChatControllerSessionValidationTest.java b/src/test/java/com/williamcallahan/javachat/web/ChatControllerSessionValidationTest.java
index 5912f321..02db83f0 100644
--- a/src/test/java/com/williamcallahan/javachat/web/ChatControllerSessionValidationTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/ChatControllerSessionValidationTest.java
@@ -40,7 +40,7 @@ void validateSession_doesNotCreateUnknownSessionAndReportsRecognizedSessionHisto
         assertEquals(SESSION_NOT_FOUND_MESSAGE, unknownSessionBody.message());
         assertFalse(chatMemoryService.hasSession(UNKNOWN_SESSION_ID));
 
-        chatMemoryService.addUser(RECOGNIZED_SESSION_ID, STORED_MESSAGE_TEXT);
+        chatMemoryService.addExchange(RECOGNIZED_SESSION_ID, STORED_MESSAGE_TEXT, "Stored assistant response");
         ResponseEntity<SessionValidationResponse> recognizedSessionEntity =
                 chatController.validateSession(RECOGNIZED_SESSION_ID);
         SessionValidationResponse recognizedSessionBody = recognizedSessionEntity.getBody();
diff --git a/src/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.java b/src/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.java
index 5bfd27cc..d8c219e9 100644
--- a/src/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/ChatControllerStreamingFailureTest.java
@@ -127,10 +127,7 @@ private List<ServerSentEvent<String>> streamFailure(Throwable streamingFailure,
         when(retrievalService.toCitations(anyList())).thenReturn(new RetrievalService.CitationOutcome(List.of(), 0));
         when(streamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
                 .thenReturn(Mono.just(new StreamingResult(
-                        Flux.error(streamingFailure),
-                        RateLimitService.ApiProvider.OPENAI,
-                        Flux.empty(),
-                        Flux.empty())));
+                        Flux.error(streamingFailure), RateLimitService.ApiProvider.OPENAI, Flux.empty())));
         when(streamingService.isRecoverableStreamingFailure(streamingFailure)).thenReturn(retryable);
 
         return chatController.stream(new ChatStreamRequest(SESSION_ID, USER_QUERY, null), new MockHttpServletResponse())
diff --git a/src/test/java/com/williamcallahan/javachat/web/GuidedLearningControllerStreamingFailureTest.java b/src/test/java/com/williamcallahan/javachat/web/GuidedLearningControllerStreamingFailureTest.java
index a28dcc3b..0c34e082 100644
--- a/src/test/java/com/williamcallahan/javachat/web/GuidedLearningControllerStreamingFailureTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/GuidedLearningControllerStreamingFailureTest.java
@@ -95,7 +95,7 @@ void guidedChatKeepsTerminalExceptionTypeOutOfRetryableClientError() throws Json
         when(guidedLearningService.citationsForBookDocuments(anyList())).thenReturn(List.of());
         when(streamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
                 .thenReturn(Mono.just(new StreamingResult(
-                        Flux.error(terminalFailure), RateLimitService.ApiProvider.OPENAI, Flux.empty(), Flux.empty())));
+                        Flux.error(terminalFailure), RateLimitService.ApiProvider.OPENAI, Flux.empty())));
         when(streamingService.isRecoverableStreamingFailure(terminalFailure)).thenReturn(true);
 
         List<ServerSentEvent<String>> streamEvents = guidedController.stream(
@@ -143,7 +143,7 @@ void guidedChatKeepsNonTerminalExceptionTypeInStructuredLogOnly() throws JsonPro
         when(guidedLearningService.citationsForBookDocuments(anyList())).thenReturn(List.of());
         when(streamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
                 .thenReturn(Mono.just(new StreamingResult(
-                        Flux.error(upstreamFailure), RateLimitService.ApiProvider.OPENAI, Flux.empty(), Flux.empty())));
+                        Flux.error(upstreamFailure), RateLimitService.ApiProvider.OPENAI, Flux.empty())));
         when(streamingService.isRecoverableStreamingFailure(upstreamFailure)).thenReturn(false);
 
         List<ServerSentEvent<String>> streamEvents = guidedController.stream(
diff --git a/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java b/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
index 335cdf01..4d0257f0 100644
--- a/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/GuidedSseCitationEventTest.java
@@ -75,8 +75,8 @@ void guidedStreamEmitsCitationEvent() throws Exception {
         given(openAIStreamingService.isAvailable()).willReturn(true);
         given(chatMemoryService.getHistory(anyString())).willReturn(List.of());
         given(openAIStreamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
-                .willReturn(Mono.just(new StreamingResult(
-                        Flux.just("Hello"), RateLimitService.ApiProvider.OPENAI, Flux.empty(), Flux.empty())));
+                .willReturn(Mono.just(
+                        new StreamingResult(Flux.just("Hello"), RateLimitService.ApiProvider.OPENAI, Flux.empty())));
         given(guidedLearningService.buildStructuredGuidedPromptWithContext(anyList(), anyString(), anyString()))
                 .willReturn(new GuidedLearningService.GuidedChatPromptOutcome(
                         StructuredPrompt.fromRawPrompt("test", 1), List.of()));
diff --git a/src/test/java/com/williamcallahan/javachat/web/StreamingProviderFallbackSseEventTest.java b/src/test/java/com/williamcallahan/javachat/web/StreamingProviderFallbackSseEventTest.java
index bc951986..a3ba19e4 100644
--- a/src/test/java/com/williamcallahan/javachat/web/StreamingProviderFallbackSseEventTest.java
+++ b/src/test/java/com/williamcallahan/javachat/web/StreamingProviderFallbackSseEventTest.java
@@ -1,7 +1,9 @@
 package com.williamcallahan.javachat.web;
 
+import static com.williamcallahan.javachat.web.SseConstants.EVENT_PROVIDER;
 import static com.williamcallahan.javachat.web.SseConstants.STATUS_CODE_STREAM_PROVIDER_FALLBACK;
 import static com.williamcallahan.javachat.web.SseConstants.STATUS_STAGE_STREAM;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyDouble;
@@ -9,6 +11,7 @@
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.BDDMockito.given;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
 import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.asyncDispatch;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
@@ -29,6 +32,7 @@
 import com.williamcallahan.javachat.service.StreamingNotice;
 import com.williamcallahan.javachat.service.StreamingResult;
 import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
@@ -39,6 +43,7 @@
 import org.springframework.test.web.servlet.MvcResult;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
+import reactor.core.publisher.Sinks;
 
 /** Verifies both chat SSE endpoints publish the provider selected after a pre-text fallback. */
 @WebMvcTest(controllers = {ChatController.class, GuidedLearningController.class})
@@ -50,12 +55,15 @@ class StreamingProviderFallbackSseEventTest {
     private static final String LESSON_SLUG = "sealed-classes";
     private static final String USER_QUERY = "explain provider fallback";
     private static final String FALLBACK_RESPONSE_TEXT = "fallback provider response";
-    private static final String INITIAL_PROVIDER_NAME = "github_models";
-    private static final String FALLBACK_PROVIDER_NAME = "openai";
+    private static final String INITIAL_PROVIDER_NAME = RateLimitService.ApiProvider.GITHUB_MODELS.getName();
+    private static final String FALLBACK_PROVIDER_NAME = RateLimitService.ApiProvider.OPENAI.getName();
 
     @Autowired
     MockMvc mockMvc;
 
+    @Autowired
+    SseSupport sseSupport;
+
     @MockitoBean
     ChatService chatService;
 
@@ -78,7 +86,7 @@ class StreamingProviderFallbackSseEventTest {
     ExceptionResponseBuilder exceptionResponseBuilder;
 
     @Test
-    void chatStreamPublishesFallbackProviderAndNoticeBeforeFallbackText() throws Exception {
+    void chatStreamConsumesReplayableFallbackNoticeOnceAndPublishesProviderAndStatusBeforeText() throws Exception {
         given(chatMemoryService.getHistory(CHAT_SESSION_ID)).willReturn(List.of());
         given(chatService.buildStructuredPromptWithContextOutcome(
                         anyList(), eq(USER_QUERY), eq(ModelConfiguration.DEFAULT_MODEL)))
@@ -86,7 +94,8 @@ void chatStreamPublishesFallbackProviderAndNoticeBeforeFallbackText() throws Exc
                         StructuredPrompt.fromRawPrompt("test", 1), List.of(), List.of()));
         given(retrievalService.toCitations(anyList())).willReturn(new RetrievalService.CitationOutcome(List.of(), 0));
         given(openAIStreamingService.isAvailable()).willReturn(true);
-        StreamingResult providerFallbackStreamingResult = providerFallbackStreamingResult();
+        AtomicInteger noticeSubscriptionCount = new AtomicInteger();
+        StreamingResult providerFallbackStreamingResult = providerFallbackStreamingResult(noticeSubscriptionCount);
         given(openAIStreamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
                 .willReturn(Mono.just(providerFallbackStreamingResult));
 
@@ -94,17 +103,23 @@ void chatStreamPublishesFallbackProviderAndNoticeBeforeFallbackText() throws Exc
                 "/api/chat/stream", "{\"sessionId\":\"" + CHAT_SESSION_ID + "\",\"message\":\"" + USER_QUERY + "\"}");
 
         assertFallbackProviderProtocol(serializedSseStream);
+        verify(chatMemoryService).addExchange(CHAT_SESSION_ID, USER_QUERY, FALLBACK_RESPONSE_TEXT);
+        assertEquals(
+                1,
+                noticeSubscriptionCount.get(),
+                "ChatController must delegate the replayed notice to one SseSupport subscription");
     }
 
     @Test
-    void guidedStreamPublishesFallbackProviderAndNoticeBeforeFallbackText() throws Exception {
+    void guidedStreamConsumesReplayableFallbackNoticeOnceAndPublishesProviderAndStatusBeforeText() throws Exception {
         given(chatMemoryService.getHistory(GUIDED_SESSION_ID)).willReturn(List.of());
         given(guidedLearningService.buildStructuredGuidedPromptWithContext(anyList(), eq(LESSON_SLUG), eq(USER_QUERY)))
                 .willReturn(new GuidedLearningService.GuidedChatPromptOutcome(
                         StructuredPrompt.fromRawPrompt("test", 1), List.of()));
         given(guidedLearningService.citationsForBookDocuments(anyList())).willReturn(List.of());
         given(openAIStreamingService.isAvailable()).willReturn(true);
-        StreamingResult providerFallbackStreamingResult = providerFallbackStreamingResult();
+        AtomicInteger noticeSubscriptionCount = new AtomicInteger();
+        StreamingResult providerFallbackStreamingResult = providerFallbackStreamingResult(noticeSubscriptionCount);
         given(openAIStreamingService.streamResponse(any(StructuredPrompt.class), anyDouble()))
                 .willReturn(Mono.just(providerFallbackStreamingResult));
 
@@ -114,9 +129,14 @@ void guidedStreamPublishesFallbackProviderAndNoticeBeforeFallbackText() throws E
                         + USER_QUERY + "\"}");
 
         assertFallbackProviderProtocol(serializedSseStream);
+        verify(chatMemoryService).addExchange(GUIDED_SESSION_ID, USER_QUERY, FALLBACK_RESPONSE_TEXT);
+        assertEquals(
+                1,
+                noticeSubscriptionCount.get(),
+                "GuidedLearningController must delegate the replayed notice to one SseSupport subscription");
     }
 
-    private StreamingResult providerFallbackStreamingResult() {
+    private StreamingResult providerFallbackStreamingResult(AtomicInteger noticeSubscriptionCount) {
         StreamingNotice fallbackNotice = mock(StreamingNotice.class);
         given(fallbackNotice.summary()).willReturn("Retrying stream with provider");
         given(fallbackNotice.diagnosticContext()).willReturn("Retrying before response text was emitted.");
@@ -127,11 +147,16 @@ private StreamingResult providerFallbackStreamingResult() {
         given(fallbackNotice.attempt()).willReturn(2);
         given(fallbackNotice.maxAttempts()).willReturn(2);
 
+        Sinks.Many<StreamingNotice> replayedNoticeSink = Sinks.many().replay().limit(1);
+        assertEquals(Sinks.EmitResult.OK, replayedNoticeSink.tryEmitNext(fallbackNotice));
+        assertEquals(Sinks.EmitResult.OK, replayedNoticeSink.tryEmitComplete());
+
+        Flux<StreamingNotice> replayedNoticeFlux = Flux.defer(() -> {
+            noticeSubscriptionCount.incrementAndGet();
+            return replayedNoticeSink.asFlux();
+        });
         return new StreamingResult(
-                Flux.just(FALLBACK_RESPONSE_TEXT),
-                RateLimitService.ApiProvider.GITHUB_MODELS,
-                Flux.just(RateLimitService.ApiProvider.OPENAI),
-                Flux.just(fallbackNotice));
+                Flux.just(FALLBACK_RESPONSE_TEXT), RateLimitService.ApiProvider.GITHUB_MODELS, replayedNoticeFlux);
     }
 
     private String serializeSseResponse(String endpoint, String requestJson) throws Exception {
@@ -149,7 +174,7 @@ private String serializeSseResponse(String endpoint, String requestJson) throws
                 .getContentAsString();
     }
 
-    private static void assertFallbackProviderProtocol(String serializedSseStream) {
+    private void assertFallbackProviderProtocol(String serializedSseStream) {
         int initialProviderEventPosition = providerEventPosition(serializedSseStream, INITIAL_PROVIDER_NAME);
         int fallbackProviderEventPosition = providerEventPosition(serializedSseStream, FALLBACK_PROVIDER_NAME);
         int fallbackNoticePosition =
@@ -167,6 +192,9 @@ private static void assertFallbackProviderProtocol(String serializedSseStream) {
         assertTrue(
                 initialProviderEventPosition < fallbackProviderEventPosition,
                 "Initial provider must precede fallback provider. Payload was:\n" + serializedSseStream);
+        assertTrue(
+                fallbackProviderEventPosition < fallbackNoticePosition,
+                "Fallback provider must precede fallback status. Payload was:\n" + serializedSseStream);
         assertTrue(
                 fallbackProviderEventPosition < fallbackTextPosition,
                 "Fallback provider must precede fallback text. Payload was:\n" + serializedSseStream);
@@ -175,13 +203,14 @@ private static void assertFallbackProviderProtocol(String serializedSseStream) {
                 "Fallback notice must precede fallback text. Payload was:\n" + serializedSseStream);
     }
 
-    private static int providerEventPosition(String serializedSseStream, String providerName) {
-        String compactProviderEvent = "event:provider\ndata:{\"provider\":\"" + providerName + "\"}";
+    private int providerEventPosition(String serializedSseStream, String providerName) {
+        String providerPayload = sseSupport.jsonSerialize(new SseSupport.ProviderPayload(providerName));
+        String compactProviderEvent = "event:" + EVENT_PROVIDER + "\ndata:" + providerPayload;
         int compactEventPosition = serializedSseStream.indexOf(compactProviderEvent);
         if (compactEventPosition >= 0) {
             return compactEventPosition;
         }
-        String spacedProviderEvent = "event: provider\ndata: {\"provider\":\"" + providerName + "\"}";
+        String spacedProviderEvent = "event: " + EVENT_PROVIDER + "\ndata: " + providerPayload;
         return serializedSseStream.indexOf(spacedProviderEvent);
     }
 }

From 54e39b69ef405fe600139a3b7e77c8e3ba8837eb Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 11:58:49 -0700
Subject: [PATCH 04/40] fix(markdown): match Java identifier boundaries

Use Java-compatible identifier continuation categories when detecting language keywords. Cover characters accepted by Unicode identifier rules but rejected by Java, plus Java-specific dollar and control characters.
---
 frontend/src/lib/services/javaLanguageDetection.ts | 2 +-
 frontend/src/lib/services/markdown.test.ts         | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/frontend/src/lib/services/javaLanguageDetection.ts b/frontend/src/lib/services/javaLanguageDetection.ts
index bb85f40c..a92c7962 100644
--- a/frontend/src/lib/services/javaLanguageDetection.ts
+++ b/frontend/src/lib/services/javaLanguageDetection.ts
@@ -15,7 +15,7 @@ const JAVA_IDENTIFIER_IGNORABLE_CONTROL_RANGES = "\\u0000-\\u0008\\u000E-\\u001B
 
 /** Matches Java identifier parts, including identifier-ignorable characters. */
 const JAVA_IDENTIFIER_PART_PATTERN = new RegExp(
-  `[\\p{ID_Continue}\\p{Sc}\\p{Cf}${JAVA_IDENTIFIER_IGNORABLE_CONTROL_RANGES}]`,
+  `[\\p{L}\\p{Nl}\\p{Sc}\\p{Pc}\\p{Nd}\\p{Mc}\\p{Mn}\\p{Cf}${JAVA_IDENTIFIER_IGNORABLE_CONTROL_RANGES}]`,
   "u",
 );
 
diff --git a/frontend/src/lib/services/markdown.test.ts b/frontend/src/lib/services/markdown.test.ts
index ccbf742e..aa228786 100644
--- a/frontend/src/lib/services/markdown.test.ts
+++ b/frontend/src/lib/services/markdown.test.ts
@@ -193,6 +193,10 @@ describe("applyJavaLanguageDetection", () => {
     const javaKeywordBoundarySnippets = [
       "int[] greetingCounts = { 1 };",
       'String.valueOf("hello");',
+      "public\u00B7ation",
+      "public\u0387ation",
+      "public\u1369ation",
+      "public\u19DAation",
     ];
 
     for (const javaKeywordBoundarySnippet of javaKeywordBoundarySnippets) {
@@ -216,6 +220,8 @@ describe("applyJavaLanguageDetection", () => {
       'const hint = "tip";',
       'const publication = "article";',
       'const republic = "state";',
+      'const public$ation = "article";',
+      'const public\u0001ation = "article";',
       'const public\uFEFFation = "article";',
     ];
 

From 93740460f5d864644a569ea287a1e24cfd3fa39e Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 11:59:10 -0700
Subject: [PATCH 05/40] refactor(learning): extract guided lesson header

Give lesson navigation and title presentation a focused component while preserving the canonical learning state in LearnView. Cover the back-to-lessons interaction through the rendered view.
---
 .../lib/components/GuidedLessonHeader.svelte  | 106 ++++++++++++++++++
 frontend/src/lib/components/LearnView.svelte  |  98 +---------------
 frontend/src/lib/components/LearnView.test.ts |   3 +
 3 files changed, 114 insertions(+), 93 deletions(-)
 create mode 100644 frontend/src/lib/components/GuidedLessonHeader.svelte

diff --git a/frontend/src/lib/components/GuidedLessonHeader.svelte b/frontend/src/lib/components/GuidedLessonHeader.svelte
new file mode 100644
index 00000000..3bd2e4a6
--- /dev/null
+++ b/frontend/src/lib/components/GuidedLessonHeader.svelte
@@ -0,0 +1,106 @@
+<script lang="ts">
+  const ALL_LESSONS_LABEL = "All Lessons";
+
+  let {
+    lessonTitle,
+    onReturnToLessons,
+  }: {
+    lessonTitle: string;
+    onReturnToLessons: () => void;
+  } = $props();
+</script>
+
+<div class="lesson-header">
+  <div class="lesson-header-inner">
+    <button
+      type="button"
+      class="back-button"
+      aria-label={ALL_LESSONS_LABEL}
+      onclick={onReturnToLessons}
+    >
+      <svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
+        <path
+          fill-rule="evenodd"
+          d="M17 10a.75.75 0 0 1-.75.75H5.612l4.158 3.96a.75.75 0 1 1-1.04 1.08l-5.5-5.25a.75.75 0 0 1 0-1.08l5.5-5.25a.75.75 0 1 1 1.04 1.08L5.612 9.25H16.25A.75.75 0 0 1 17 10Z"
+          clip-rule="evenodd"
+        />
+      </svg>
+      <span>{ALL_LESSONS_LABEL}</span>
+    </button>
+    <h2 class="lesson-title">{lessonTitle}</h2>
+  </div>
+</div>
+
+<style>
+  .lesson-header {
+    flex-shrink: 0;
+    padding: var(--space-4) var(--space-6);
+    border-bottom: 1px solid var(--color-border-subtle);
+    background: var(--color-bg-secondary);
+  }
+
+  .lesson-header-inner {
+    display: flex;
+    align-items: center;
+    gap: var(--space-4);
+    max-width: 1400px;
+    margin: 0 auto;
+    width: 100%;
+  }
+
+  .back-button {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding: var(--space-2) var(--space-3);
+    background: transparent;
+    border: 1px solid var(--color-border-default);
+    border-radius: var(--radius-md);
+    font-size: var(--text-sm);
+    line-height: 1;
+    color: var(--color-text-secondary);
+    cursor: pointer;
+    transition: all var(--duration-fast) var(--ease-out);
+  }
+
+  .back-button:hover {
+    background: var(--color-bg-tertiary);
+    color: var(--color-text-primary);
+  }
+
+  .back-button svg {
+    width: 16px;
+    height: 16px;
+  }
+
+  .lesson-title {
+    font-family: var(--font-serif);
+    font-size: var(--text-xl);
+    font-weight: 500;
+    color: var(--color-text-primary);
+    letter-spacing: var(--tracking-tight);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    line-height: 1;
+    margin: 0;
+    padding-bottom: 2px;
+  }
+
+  @media (max-width: 768px) {
+    .lesson-header {
+      padding: var(--space-3) var(--space-4);
+    }
+
+    .lesson-title {
+      font-size: var(--text-lg);
+    }
+  }
+
+  @media (max-width: 640px) {
+    .back-button span {
+      display: none;
+    }
+  }
+</style>
diff --git a/frontend/src/lib/components/LearnView.svelte b/frontend/src/lib/components/LearnView.svelte
index c07340d3..da6e5ca6 100644
--- a/frontend/src/lib/components/LearnView.svelte
+++ b/frontend/src/lib/components/LearnView.svelte
@@ -14,6 +14,7 @@
     import { applyJavaLanguageDetection } from "../services/javaLanguageDetection";
     import { parseMarkdown } from "../services/markdown";
     import CitationPanel from "./CitationPanel.svelte";
+    import GuidedLessonHeader from "./GuidedLessonHeader.svelte";
     import GuidedLessonChatPanel from "./GuidedLessonChatPanel.svelte";
     import LessonCitations from "./LessonCitations.svelte";
     import MessageBubble from "./MessageBubble.svelte";
@@ -606,31 +607,10 @@
     {:else}
         <!-- Lesson View -->
         <div class="lesson-container">
-            <!-- Lesson Header - full width with inner constraint -->
-            <div class="lesson-header">
-                <div class="lesson-header-inner">
-                    <button
-                        type="button"
-                        class="back-btn"
-                        aria-label="All Lessons"
-                        onclick={goBack}
-                    >
-                        <svg
-                            viewBox="0 0 20 20"
-                            fill="currentColor"
-                            aria-hidden="true"
-                        >
-                            <path
-                                fill-rule="evenodd"
-                                d="M17 10a.75.75 0 0 1-.75.75H5.612l4.158 3.96a.75.75 0 1 1-1.04 1.08l-5.5-5.25a.75.75 0 0 1 0-1.08l5.5-5.25a.75.75 0 1 1 1.04 1.08L5.612 9.25H16.25A.75.75 0 0 1 17 10Z"
-                                clip-rule="evenodd"
-                            />
-                        </svg>
-                        <span>All Lessons</span>
-                    </button>
-                    <h2 class="lesson-title-header">{selectedLesson.title}</h2>
-                </div>
-            </div>
+            <GuidedLessonHeader
+                lessonTitle={selectedLesson.title}
+                onReturnToLessons={goBack}
+            />
 
             <!-- Two-column layout: Content + Chat (desktop) -->
             <div class="lesson-layout">
@@ -909,62 +889,6 @@
         position: relative;
     }
 
-    .lesson-header {
-        flex-shrink: 0;
-        padding: var(--space-4) var(--space-6);
-        border-bottom: 1px solid var(--color-border-subtle);
-        background: var(--color-bg-secondary);
-    }
-
-    .lesson-header-inner {
-        display: flex;
-        align-items: center;
-        gap: var(--space-4);
-        max-width: 1400px;
-        margin: 0 auto;
-        width: 100%;
-    }
-
-    .back-btn {
-        flex-shrink: 0;
-        display: flex;
-        align-items: center;
-        gap: var(--space-2);
-        padding: var(--space-2) var(--space-3);
-        background: transparent;
-        border: 1px solid var(--color-border-default);
-        border-radius: var(--radius-md);
-        font-size: var(--text-sm);
-        line-height: 1;
-        color: var(--color-text-secondary);
-        cursor: pointer;
-        transition: all var(--duration-fast) var(--ease-out);
-    }
-
-    .back-btn:hover {
-        background: var(--color-bg-tertiary);
-        color: var(--color-text-primary);
-    }
-
-    .back-btn svg {
-        width: 16px;
-        height: 16px;
-    }
-
-    .lesson-title-header {
-        font-family: var(--font-serif);
-        font-size: var(--text-xl);
-        font-weight: 500;
-        color: var(--color-text-primary);
-        letter-spacing: var(--tracking-tight);
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        line-height: 1;
-        margin: 0;
-        padding-bottom: 2px;
-    }
-
     /* Two-column Layout */
     .lesson-layout {
         flex: 1;
@@ -1099,14 +1023,6 @@
             font-size: var(--text-base);
         }
 
-        .lesson-header {
-            padding: var(--space-3) var(--space-4);
-        }
-
-        .lesson-title-header {
-            font-size: var(--text-lg);
-        }
-
         .lesson-content-panel {
             padding: var(--space-4);
         }
@@ -1134,9 +1050,5 @@
         .lesson-summary {
             font-size: var(--text-xs);
         }
-
-        .back-btn span {
-            display: none;
-        }
     }
 </style>
diff --git a/frontend/src/lib/components/LearnView.test.ts b/frontend/src/lib/components/LearnView.test.ts
index 05fe28a8..6242998b 100644
--- a/frontend/src/lib/components/LearnView.test.ts
+++ b/frontend/src/lib/components/LearnView.test.ts
@@ -53,6 +53,9 @@ describe("LearnView guided chat streaming stability", () => {
     const allLessonsButton = await findByRole("button", { name: "All Lessons" });
     expect(allLessonsButton).toHaveAttribute("aria-label", "All Lessons");
     expect(allLessonsButton).toHaveTextContent("All Lessons");
+
+    await fireEvent.click(allLessonsButton);
+    expect(await findByRole("button", { name: /test lesson/i })).toBeInTheDocument();
   });
 
   it("keeps the guided assistant message DOM node stable when the stream completes", async () => {

From ae4b64ff64d3f5f28d45e0abadb22b66c99c2026 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:00:24 -0700
Subject: [PATCH 06/40] fix(streaming): commit exchanges after completion

Record the user and assistant turns only after chat or guided streaming completes. This keeps the controller call sites aligned with the atomic memory API and leaves failed streams out of session history.
---
 .../java/com/williamcallahan/javachat/web/ChatController.java | 4 +---
 .../javachat/web/GuidedLearningController.java                | 3 +--
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/web/ChatController.java b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
index 9115b73e..7f3c7b90 100644
--- a/src/main/java/com/williamcallahan/javachat/web/ChatController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/ChatController.java
@@ -121,8 +121,6 @@ public Flux<ServerSentEvent<String>> stream(
         List<Message> history = chatMemory.getHistory(sessionId);
         PIPELINE_LOG.info("[{}] Chat history loaded", requestToken);
 
-        chatMemory.addUser(sessionId, userQuery);
-
         return Flux.defer(() -> {
                     // Build structured prompt for intelligent truncation
                     // Pass model hint to optimize RAG for token-constrained models
@@ -191,7 +189,7 @@ public Flux<ServerSentEvent<String>> stream(
                                             citationEvent);
                                 })
                                 .doOnComplete(() -> {
-                                    chatMemory.addAssistant(sessionId, fullResponse.toString());
+                                    chatMemory.addExchange(sessionId, userQuery, fullResponse.toString());
                                     PIPELINE_LOG.info("[{}] STREAMING COMPLETE", requestToken);
                                 });
                     }
diff --git a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
index db276d54..402d68a5 100644
--- a/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
+++ b/src/main/java/com/williamcallahan/javachat/web/GuidedLearningController.java
@@ -250,7 +250,6 @@ public Flux<ServerSentEvent<String>> stream(
      */
     private Flux<ServerSentEvent<String>> streamGuidedResponse(String sessionId, String userQuery, String lessonSlug) {
         List<org.springframework.ai.chat.messages.Message> history = chatMemory.getHistory(sessionId);
-        chatMemory.addUser(sessionId, userQuery);
         return Flux.defer(() -> {
                     StringBuilder fullResponse = new StringBuilder();
 
@@ -308,7 +307,7 @@ private Flux<ServerSentEvent<String>> streamGuidedResponse(String sessionId, Str
                                         Flux.merge(runtimeStreamingEvents, dataEvents, heartbeats),
                                         citationEvent);
                             })
-                            .doOnComplete(() -> chatMemory.addAssistant(sessionId, fullResponse.toString()));
+                            .doOnComplete(() -> chatMemory.addExchange(sessionId, userQuery, fullResponse.toString()));
                 })
                 .onErrorResume(error -> {
                     Optional<ReportedStreamingFailure> terminalFailureContext =

From 5a2beb1d0f485ca2c69e05a8f88511c863b3db09 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:07:02 -0700
Subject: [PATCH 07/40] fix(ingestion): align manifest line ending parsing

---
 scripts/lib/documentation_sources.sh          |  1 +
 .../config/JavaApiDocumentationManifest.java  | 13 +++--
 .../JavaApiDocumentationManifestTest.java     | 55 +++++++++++++++----
 3 files changed, 53 insertions(+), 16 deletions(-)

diff --git a/scripts/lib/documentation_sources.sh b/scripts/lib/documentation_sources.sh
index a0ed3d02..9d4f8966 100644
--- a/scripts/lib/documentation_sources.sh
+++ b/scripts/lib/documentation_sources.sh
@@ -70,6 +70,7 @@ load_java_api_documentation_sources() {
     local retained_relative_mirror_paths=("")
     while IFS= read -r manifest_line || [ -n "$manifest_line" ]; do
         manifest_line_number=$((manifest_line_number + 1))
+        manifest_line="${manifest_line%$'\r'}"
         if [ "$manifest_line_number" -eq 1 ]; then
             manifest_header="$manifest_line"
             if [ -z "$manifest_header" ]; then
diff --git a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
index c9b25a51..9dd72c1e 100644
--- a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
+++ b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
@@ -35,16 +35,21 @@ static List<JavaApiDocumentationSource> load() {
             throw new IllegalStateException("Canonical Java API documentation source manifest is missing");
         }
 
-        try (manifestStream;
-                BufferedReader manifestReader =
-                        new BufferedReader(new InputStreamReader(manifestStream, StandardCharsets.UTF_8))) {
-            return parse(manifestReader.lines().toList());
+        try {
+            return parse(manifestStream);
         } catch (IOException manifestReadError) {
             throw new IllegalStateException(
                     "Canonical Java API documentation source manifest could not be read", manifestReadError);
         }
     }
 
+    static List<JavaApiDocumentationSource> parse(InputStream manifestStream) throws IOException {
+        try (BufferedReader manifestReader =
+                new BufferedReader(new InputStreamReader(manifestStream, StandardCharsets.UTF_8))) {
+            return parse(manifestReader.lines().toList());
+        }
+    }
+
     static List<JavaApiDocumentationSource> parse(List<String> manifestLines) {
         if (manifestLines.size() < 2) {
             throw new IllegalStateException("Canonical Java API documentation source manifest has no records");
diff --git a/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
index d8626402..2453bade 100644
--- a/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
+++ b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
@@ -1,9 +1,11 @@
 package com.williamcallahan.javachat.config;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -22,6 +24,25 @@ class JavaApiDocumentationManifestTest {
     @TempDir
     Path temporaryDirectory;
 
+    @Test
+    void acceptsSharedCrLfManifestFixtureInJavaAndBash() throws IOException, InterruptedException {
+        String canonicalManifestText = Files.readString(CANONICAL_MANIFEST_PATH, StandardCharsets.UTF_8);
+        String crLfManifestText = canonicalManifestText.replace("\n", "\r\n");
+        Path crLfManifestPath = temporaryDirectory.resolve("crlf.manifest");
+        Files.writeString(crLfManifestPath, crLfManifestText, StandardCharsets.UTF_8);
+
+        try (InputStream manifestStream = Files.newInputStream(crLfManifestPath)) {
+            List<String> javaProjectionRows = JavaApiDocumentationManifest.parse(manifestStream).stream()
+                    .map(DocsSourceRegistry.JavaApiDocumentationSource::toManifestRow)
+                    .toList();
+            List<String> canonicalRows = canonicalManifestText.lines().skip(1).toList();
+            assertEquals(canonicalRows, javaProjectionRows);
+        }
+
+        ShellValidation shellValidation = runShellValidation(crLfManifestPath);
+        assertEquals(0, shellValidation.exitCode(), shellValidation.standardOutput());
+    }
+
     @Test
     void rejectsSharedInvalidManifestFixturesInJavaAndBash() throws IOException, InterruptedException {
         List<String> canonicalManifestLines = Files.readAllLines(CANONICAL_MANIFEST_PATH, StandardCharsets.UTF_8);
@@ -52,21 +73,29 @@ void rejectsSharedInvalidManifestFixturesInJavaAndBash() throws IOException, Int
 
             Path invalidManifestPath = temporaryDirectory.resolve("invalid-manifest-" + fixtureIndex + ".manifest");
             Files.write(invalidManifestPath, invalidManifestLines, StandardCharsets.UTF_8);
-            Process bashValidation = new ProcessBuilder(
-                            "/bin/bash",
-                            "-c",
-                            "source \"$1\"; load_java_api_documentation_sources \"$2\"",
-                            "manifest-validation",
-                            SHELL_INTERPRETER_PATH.toAbsolutePath().toString(),
-                            invalidManifestPath.toString())
-                    .redirectErrorStream(true)
-                    .start();
-            String bashOutput = new String(bashValidation.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
-            int bashExitCode = bashValidation.waitFor();
-            assertNotEquals(0, bashExitCode, "Bash accepted invalid fixture " + fixtureIndex + ": " + bashOutput);
+            ShellValidation shellValidation = runShellValidation(invalidManifestPath);
+            assertNotEquals(
+                    0,
+                    shellValidation.exitCode(),
+                    "Bash accepted invalid fixture " + fixtureIndex + ": " + shellValidation.standardOutput());
         }
     }
 
+    private static ShellValidation runShellValidation(Path manifestPath) throws IOException, InterruptedException {
+        Process bashValidation = new ProcessBuilder(
+                        "/bin/bash",
+                        "-c",
+                        "source \"$1\"; load_java_api_documentation_sources \"$2\"",
+                        "manifest-validation",
+                        SHELL_INTERPRETER_PATH.toAbsolutePath().toString(),
+                        manifestPath.toString())
+                .redirectErrorStream(true)
+                .start();
+        String standardOutput = new String(bashValidation.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
+        int exitCode = bashValidation.waitFor();
+        return new ShellValidation(exitCode, standardOutput);
+    }
+
     private static List<String> withLine(List<String> manifestLines, int lineIndex, String replacementLine) {
         List<String> changedManifestLines = new ArrayList<>(manifestLines);
         changedManifestLines.set(lineIndex, replacementLine);
@@ -103,4 +132,6 @@ private static List<String> withDuplicateMirrorPath(List<String> manifestLines)
         changedManifestLines.add(String.join("|", duplicateMirrorColumns));
         return List.copyOf(changedManifestLines);
     }
+
+    private record ShellValidation(int exitCode, String standardOutput) {}
 }

From 111a320b0da5b7ea07da155d2e93ac381b1b5285 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:07:18 -0700
Subject: [PATCH 08/40] test(retrieval): derive Javadoc URLs from catalog

---
 .../javachat/service/RetrievalServiceTest.java     | 14 ++++++++------
 .../util/JavadocTypeCanonicalizerTest.java         |  5 ++++-
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
index b62964a9..06f6fb4a 100644
--- a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
@@ -11,6 +11,7 @@
 import static org.mockito.Mockito.when;
 
 import com.williamcallahan.javachat.config.AppProperties;
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import java.util.List;
 import org.junit.jupiter.api.Test;
 import org.springframework.ai.document.Document;
@@ -56,6 +57,9 @@ void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations()
         AppProperties appProperties = new AppProperties();
         RetrievalService retrievalService =
                 new RetrievalService(hybridSearchService, appProperties, rerankerService, documentFactory);
+        String javaApiBaseUrl =
+                DocsSourceRegistry.javaApiDocumentationSources().getFirst().remoteBaseUrl();
+        String stringJavadocUrl = javaApiBaseUrl + "java.base/java/lang/String.html";
 
         Document urlOnlyDocument = Document.builder()
                 .id("url-only")
@@ -70,19 +74,19 @@ void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations()
         Document firstJavadocChunk = Document.builder()
                 .id("first-javadoc-chunk")
                 .text("First Javadoc chunk")
-                .metadata("url", "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html")
+                .metadata("url", stringJavadocUrl)
                 .metadata("hash", "first-content-hash")
                 .build();
         Document secondJavadocChunkWithDistinctHash = Document.builder()
                 .id("second-javadoc-chunk")
                 .text("Second Javadoc chunk")
-                .metadata("url", "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html#assert(...)")
+                .metadata("url", stringJavadocUrl + "#assert(...)")
                 .metadata("hash", "second-content-hash")
                 .build();
         Document sameContentHashWithDifferentUrl = Document.builder()
                 .id("same-content-hash")
                 .text("Duplicate content under another URL")
-                .metadata("url", "https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Object.html")
+                .metadata("url", javaApiBaseUrl + "java.base/java/lang/Object.html")
                 .metadata("hash", "first-content-hash")
                 .build();
         List<Document> retrievalCandidates = List.of(
@@ -105,9 +109,7 @@ void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations()
                 List.of(urlOnlyDocument, firstJavadocChunk, secondJavadocChunkWithDistinctHash),
                 retrievalOutcome.documents());
         assertEquals(2, citationOutcome.citations().size());
-        assertEquals(
-                "https://docs.oracle.com/en/java/javase/21/relnotes/21-0-2-relnotes.html",
-                citationOutcome.citations().get(1).getUrl());
+        assertEquals(stringJavadocUrl, citationOutcome.citations().get(1).getUrl());
         assertEquals("First Javadoc chunk", citationOutcome.citations().get(1).getSnippet());
         assertEquals(0, citationOutcome.failedConversionCount());
     }
diff --git a/src/test/java/com/williamcallahan/javachat/util/JavadocTypeCanonicalizerTest.java b/src/test/java/com/williamcallahan/javachat/util/JavadocTypeCanonicalizerTest.java
index de2cc736..19cbfe8d 100644
--- a/src/test/java/com/williamcallahan/javachat/util/JavadocTypeCanonicalizerTest.java
+++ b/src/test/java/com/williamcallahan/javachat/util/JavadocTypeCanonicalizerTest.java
@@ -3,6 +3,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import java.util.Optional;
 import org.junit.jupiter.api.Test;
 
@@ -19,7 +20,9 @@ void canonicalizeTypeReturnsEmptyForGenericOnlyToken() {
 
     @Test
     void refineMemberAnchorUrlIgnoresGenericOnlyMethodParameterFragment() {
-        String classPageUrl = "https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/String.html";
+        String classPageUrl =
+                DocsSourceRegistry.javaApiDocumentationSources().getFirst().remoteBaseUrl()
+                        + "java.base/java/lang/String.html";
         String surroundingDocText = "Use parse(<T>) to parse values.";
 
         String refinedUrl =

From a97a5e398a6ecc8bdc2ce1d340a4e0b42079f17e Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:17:23 -0700
Subject: [PATCH 09/40] style(ingestion): name manifest record threshold

---
 .../javachat/config/JavaApiDocumentationManifest.java          | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
index 9dd72c1e..563a6b7b 100644
--- a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
+++ b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
@@ -25,6 +25,7 @@ final class JavaApiDocumentationManifest {
     private static final String MANIFEST_RESOURCE = "/java-api-documentation-sources.manifest";
     private static final String MANIFEST_DELIMITER = "|";
     private static final String MANIFEST_DELIMITER_REGEX = "\\|";
+    private static final int MINIMUM_MANIFEST_LINE_COUNT = 2;
     private static final Pattern CANONICAL_UNSIGNED_INTEGER = Pattern.compile("(?:0|[1-9][0-9]*)");
 
     private JavaApiDocumentationManifest() {}
@@ -51,7 +52,7 @@ static List<JavaApiDocumentationSource> parse(InputStream manifestStream) throws
     }
 
     static List<JavaApiDocumentationSource> parse(List<String> manifestLines) {
-        if (manifestLines.size() < 2) {
+        if (manifestLines.size() < MINIMUM_MANIFEST_LINE_COUNT) {
             throw new IllegalStateException("Canonical Java API documentation source manifest has no records");
         }
         validateHeader(manifestLines.get(0));

From faf139300a9aa2e278156a3c4f2536e344e40079 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:26:59 -0700
Subject: [PATCH 10/40] feat(ingestion): honor per-source partial mirror policy

Oracle Javadoc mirrors can legitimately land below their expected HTML
minimum on an interrupted or throttled fetch, yet the fixed threshold
treated any short mirror as a hard failure and quarantined the partial
result, discarding work that incremental reruns could resume.

Thread the manifest's seventh projection field (ALLOW_PARTIAL) through
fetch_docs and its Oracle/generic helpers so sources flagged partial keep
a validated short mirror with a warning instead of failing, and skip the
pre-fetch quarantine that would erase it. Extract fetch_documentation_source
to project one seven-field row into the fetch boundary and guard the script
so it can be sourced by tests without executing.

- Add partial_mirror_allowed parameter to validate_fetch_result,
  fetch_oracle_javadoc_seed, fetch_docs_mirror, and fetch_docs
- Add fetch_documentation_source to parse and dispatch a seven-field row
- Add scripts/test_java_api_fetch_projection.sh asserting manifest rows
  retain seven distinct fetch fields in order
---
 scripts/fetch_all_docs.sh                 | 106 +++++++++++++++-------
 scripts/test_java_api_fetch_projection.sh |  73 +++++++++++++++
 2 files changed, 146 insertions(+), 33 deletions(-)
 create mode 100755 scripts/test_java_api_fetch_projection.sh

diff --git a/scripts/fetch_all_docs.sh b/scripts/fetch_all_docs.sh
index e045c636..e6fe0595 100755
--- a/scripts/fetch_all_docs.sh
+++ b/scripts/fetch_all_docs.sh
@@ -160,11 +160,13 @@ quarantine_versioned_reference_subdirs() {
 #   $2 - target directory (for HTML count)
 #   $3 - human-readable name
 #   $4 - minimum required HTML files (0 = no minimum)
+#   $5 - whether a validated partial mirror is accepted
 validate_fetch_result() {
     local wget_exit_code="$1"
     local target_dir="$2"
     local name="$3"
     local min_files="$4"
+    local partial_mirror_allowed="$5"
 
     local fetched_html_count
     fetched_html_count="$(count_html_files "$target_dir")"
@@ -178,8 +180,12 @@ validate_fetch_result() {
 
     log "${GREEN}✓ $name fetched successfully: $fetched_html_count HTML files${NC}"
     if [ "$min_files" -gt 0 ] && [ "$fetched_html_count" -lt "$min_files" ]; then
-        log "${RED}✗ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+)${NC}"
-        return 1
+        if [ "$partial_mirror_allowed" = "true" ]; then
+            log "${YELLOW}⚠ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+); keeping partial mirror for incremental reruns${NC}"
+        else
+            log "${RED}✗ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+)${NC}"
+            return 1
+        fi
     fi
     return 0
 }
@@ -193,12 +199,14 @@ validate_fetch_result() {
 #   $3 - human-readable name
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
+#   $6 - whether a validated partial mirror is accepted
 fetch_oracle_javadoc_seed() {
     local url="$1"
     local target_dir="$2"
     local name="$3"
     local cut_dirs="$4"
     local min_files="$5"
+    local partial_mirror_allowed="$6"
 
     local seed_file="$target_dir/.oracle-javadoc-seed.txt"
     log "${BLUE}ℹ Oracle Javadoc detected; generating explicit URL seed list...${NC}"
@@ -229,7 +237,7 @@ fetch_oracle_javadoc_seed() {
     local wget_exit_code=$?
     cd - > /dev/null
 
-    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files"
+    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files" "$partial_mirror_allowed"
 }
 
 # Fetches documentation using wget --mirror for generic (non-Oracle) sites.
@@ -241,6 +249,7 @@ fetch_oracle_javadoc_seed() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
+#   $7 - whether a validated partial mirror is accepted
 fetch_docs_mirror() {
     local url="$1"
     local target_dir="$2"
@@ -248,6 +257,7 @@ fetch_docs_mirror() {
     local cut_dirs="$4"
     local min_files="$5"
     local reject_regex="${6:-}"
+    local partial_mirror_allowed="$7"
 
     local wget_args=(
         --mirror \
@@ -280,7 +290,7 @@ fetch_docs_mirror() {
     local wget_exit_code=$?
     cd - > /dev/null
 
-    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files"
+    validate_fetch_result "$wget_exit_code" "$target_dir" "$name" "$min_files" "$partial_mirror_allowed"
 }
 
 # Dispatches documentation fetching: performs pre-fetch housekeeping (existing
@@ -294,6 +304,7 @@ fetch_docs_mirror() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
+#   $7 - whether a validated partial mirror is accepted
 fetch_docs() {
     local url="$1"
     local target_dir="$2"
@@ -301,6 +312,7 @@ fetch_docs() {
     local cut_dirs="$4"
     local min_files="$5"
     local reject_regex="${6:-}"
+    local partial_mirror_allowed="$7"
 
     # Allow config-friendly placeholder for regex alternation without breaking our field delimiter.
     reject_regex="${reject_regex//__OR__/|}"
@@ -311,7 +323,7 @@ fetch_docs() {
     if [ "$existing_count" -gt 0 ]; then
         log "${BLUE}ℹ Existing mirror: $existing_count HTML files${NC}"
     fi
-    if [ "$min_files" -gt 0 ] && [ "$existing_count" -gt 0 ] && [ "$existing_count" -lt "$min_files" ]; then
+    if [ "$partial_mirror_allowed" != "true" ] && [ "$min_files" -gt 0 ] && [ "$existing_count" -gt 0 ] && [ "$existing_count" -lt "$min_files" ]; then
         quarantine_incomplete_dir "$target_dir" "$name" "$existing_count" "$min_files"
     fi
 
@@ -336,35 +348,70 @@ fetch_docs() {
             log "${GREEN}✓ $name already fetched: $existing_count HTML files (minimum: $min_files)${NC}"
             return 0
         fi
-        fetch_oracle_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files"
+        fetch_oracle_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$partial_mirror_allowed"
     else
-        fetch_docs_mirror "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex"
+        fetch_docs_mirror "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex" "$partial_mirror_allowed"
+    fi
+}
+
+# Projects one seven-field documentation source row into the fetch boundary.
+fetch_documentation_source() {
+    local documentation_source_projection="$1"
+    local fetch_projection_delimiters="${documentation_source_projection//[^|]/}"
+    if [ "${#fetch_projection_delimiters}" -ne 6 ]; then
+        log "${RED}✗ Documentation source projection must contain exactly seven fields${NC}"
+        return 1
+    fi
+
+    local documentation_source_url
+    local mirror_directory
+    local documentation_source_name
+    local cut_directories
+    local minimum_html_files
+    local reject_regex
+    local partial_mirror_allowed
+    IFS='|' read -r documentation_source_url mirror_directory documentation_source_name cut_directories minimum_html_files reject_regex partial_mirror_allowed <<< "$documentation_source_projection"
+
+    if [ "$partial_mirror_allowed" != "true" ] && [ "$partial_mirror_allowed" != "false" ]; then
+        log "${RED}✗ Documentation source partial-mirror policy must be true or false${NC}"
+        return 1
     fi
+
+    echo ""
+    log "Processing: $documentation_source_name"
+    log "URL: $documentation_source_url"
+    log "Target: $mirror_directory"
+
+    fetch_docs "$documentation_source_url" "$mirror_directory" "$documentation_source_name" "$cut_directories" "$minimum_html_files" "$reject_regex" "$partial_mirror_allowed"
 }
 
+if [[ "${BASH_SOURCE[0]}" != "$0" ]]; then
+    return 0
+fi
+
 # Documentation sources configuration
-# Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX
+# Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX|ALLOW_PARTIAL
 DOC_SOURCES=(
     # Spring Boot (current)
-    "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot-complete|Spring Boot Reference (current)|1|50|"
-    "${SPRING_BOOT_API_BASE:-https://docs.spring.io/spring-boot/api/}|$DOCS_ROOT/spring-boot-complete|Spring Boot API (current)|1|7000|"
+    "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot-complete|Spring Boot Reference (current)|1|50||false"
+    "${SPRING_BOOT_API_BASE:-https://docs.spring.io/spring-boot/api/}|$DOCS_ROOT/spring-boot-complete|Spring Boot API (current)|1|7000||false"
 
     # Spring AI
     # Stable reference (1.1.x) - avoid pulling versioned reference subtrees (including 2.0) and SNAPSHOT content.
-    "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai-reference|Spring AI Reference (stable)|1|80|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT"
+    "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai-reference|Spring AI Reference (stable)|1|80|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
     # 2.0 reference (milestone) - avoid SNAPSHOT content.
-    "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-reference-2|Spring AI Reference (2.0)|1|80|/spring-ai/reference/[^/]*SNAPSHOT"
+    "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-reference-2|Spring AI Reference (2.0)|1|80|/spring-ai/reference/[^/]*SNAPSHOT|false"
     # API docs (stable + 2.x). Keep these separate to avoid quarantine/validation conflicts.
-    "${SPRING_AI_API_STABLE_BASE:-https://docs.spring.io/spring-ai/docs/current/api/}|$DOCS_ROOT/spring-ai-api-stable|Spring AI API (stable)|1|200|"
-    "${SPRING_AI_API_2_BASE:-https://docs.spring.io/spring-ai/docs/2.0.x/api/}|$DOCS_ROOT/spring-ai-api-2|Spring AI API (2.x)|1|200|"
+    "${SPRING_AI_API_STABLE_BASE:-https://docs.spring.io/spring-ai/docs/current/api/}|$DOCS_ROOT/spring-ai-api-stable|Spring AI API (stable)|1|200||false"
+    "${SPRING_AI_API_2_BASE:-https://docs.spring.io/spring-ai/docs/2.0.x/api/}|$DOCS_ROOT/spring-ai-api-2|Spring AI API (2.x)|1|200||false"
 
     # Spring Framework (current) - avoid pulling older reference versions under /reference/6.x, etc.
-    "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Reference (current)|1|3000|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT"
-    "${SPRING_FRAMEWORK_API_BASE:-https://docs.spring.io/spring-framework/docs/current/javadoc-api/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Javadoc (current)|1|7000|"
+    "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Reference (current)|1|3000|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
+    "${SPRING_FRAMEWORK_API_BASE:-https://docs.spring.io/spring-framework/docs/current/javadoc-api/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Javadoc (current)|1|7000||false"
 
-    "${JAVA25_RELEASE_NOTES_ISSUES_URL:-https://www.oracle.com/java/technologies/javase/25-relnote-issues.html}|$DOCS_ROOT/oracle/javase|Java 25 Release Notes Issues|3|1|"
-    "${IBM_JAVA25_ARTICLE_URL:-https://developer.ibm.com/articles/java-whats-new-java25/}|$DOCS_ROOT/ibm/articles|IBM Java 25 Overview|1|1|"
-    "${JETBRAINS_JAVA25_BLOG_URL:-https://blog.jetbrains.com/idea/2025/09/java-25-lts-and-intellij-idea/}|$DOCS_ROOT/jetbrains/idea/2025/09|JetBrains Java 25 Blog|3|1|"
+    "${JAVA25_RELEASE_NOTES_ISSUES_URL:-https://www.oracle.com/java/technologies/javase/25-relnote-issues.html}|$DOCS_ROOT/oracle/javase|Java 25 Release Notes Issues|3|1||false"
+    "${IBM_JAVA25_ARTICLE_URL:-https://developer.ibm.com/articles/java-whats-new-java25/}|$DOCS_ROOT/ibm/articles|IBM Java 25 Overview|1|1||false"
+    "${JETBRAINS_JAVA25_BLOG_URL:-https://blog.jetbrains.com/idea/2025/09/java-25-lts-and-intellij-idea/}|$DOCS_ROOT/jetbrains/idea/2025/09|JetBrains Java 25 Blog|3|1||false"
 )
 
 load_java_api_documentation_sources "$JAVA_API_SOURCES_MANIFEST"
@@ -377,10 +424,10 @@ fi
 
 if [ "$INCLUDE_QUICK" = "true" ]; then
     DOC_SOURCES+=(
-        "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot|Spring Boot Quick (reference landing)|1|1|"
-        "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework|Spring Framework Quick (reference landing)|1|1|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT"
-        "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai|Spring AI Quick (reference landing)|1|1|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT"
-        "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-2|Spring AI Quick (2.0 landing)|1|1|/spring-ai/reference/[^/]*SNAPSHOT"
+        "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot|Spring Boot Quick (reference landing)|1|1||false"
+        "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework|Spring Framework Quick (reference landing)|1|1|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
+        "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai|Spring AI Quick (reference landing)|1|1|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
+        "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-2|Spring AI Quick (2.0 landing)|1|1|/spring-ai/reference/[^/]*SNAPSHOT|false"
     )
 fi
 
@@ -403,19 +450,12 @@ log "Starting documentation fetch process..."
 echo "=============================================="
 
 # Process each documentation source
-for source in "${DOC_SOURCES[@]}"; do
-    IFS='|' read -r url target_dir name cut_dirs min_files reject_regex <<< "$source"
-    
-    echo ""
-    log "Processing: $name"
-    log "URL: $url"
-    log "Target: $target_dir"
-    
-    if fetch_docs "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "${reject_regex:-}"; then
+for documentation_source_projection in "${DOC_SOURCES[@]}"; do
+    if fetch_documentation_source "$documentation_source_projection"; then
         TOTAL_FETCHED=$((TOTAL_FETCHED + 1))
     else
         TOTAL_FAILED=$((TOTAL_FAILED + 1))
-        log "${RED}Error: Failed to fetch $name; auditing the remaining sources before exit${NC}"
+        log "${RED}Error: Failed to fetch documentation source; auditing the remaining sources before exit${NC}"
     fi
 done
 
diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
new file mode 100755
index 00000000..d7e2c696
--- /dev/null
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+
+# Verifies that canonical Java API manifest rows retain their seven-field fetch projection.
+
+set -euo pipefail
+
+TEST_SCRIPT_DIRECTORY="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$TEST_SCRIPT_DIRECTORY/.." && pwd)"
+FETCH_SCRIPT="$PROJECT_ROOT/scripts/fetch_all_docs.sh"
+JAVA_API_SOURCES_MANIFEST="$PROJECT_ROOT/src/main/resources/java-api-documentation-sources.manifest"
+TEST_DOCS_ROOT="/canonical-test-docs"
+
+fail_java_api_fetch_projection_test() {
+    local failure_message="$1"
+    printf 'FAIL: %s\n' "$failure_message" >&2
+    exit 1
+}
+
+test_script_arguments=("$@")
+set --
+# shellcheck source=fetch_all_docs.sh
+source "$FETCH_SCRIPT"
+set -- "${test_script_arguments[@]}"
+
+log() {
+    :
+}
+
+fetch_execution_arguments=()
+fetch_docs() {
+    fetch_execution_arguments=("$@")
+}
+
+JAVA_API_SOURCE_PROJECTIONS=()
+load_java_api_documentation_sources "$JAVA_API_SOURCES_MANIFEST"
+DOC_SOURCES=()
+append_java_api_fetch_sources "$TEST_DOCS_ROOT"
+
+if [ "${#JAVA_API_SOURCE_PROJECTIONS[@]}" -ne "${#DOC_SOURCES[@]}" ]; then
+    fail_java_api_fetch_projection_test "fetch projections did not preserve the complete manifest order"
+fi
+
+for java_api_source_index in "${!JAVA_API_SOURCE_PROJECTIONS[@]}"; do
+    manifest_projection="${JAVA_API_SOURCE_PROJECTIONS[$java_api_source_index]}"
+    documentation_fetch_projection="${DOC_SOURCES[$java_api_source_index]}"
+    fetch_projection_delimiters="${documentation_fetch_projection//[^|]/}"
+    if [ "${#fetch_projection_delimiters}" -ne 6 ]; then
+        fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index must contain exactly seven fields"
+    fi
+
+    fetch_execution_arguments=()
+    fetch_documentation_source "$documentation_fetch_projection" > /dev/null
+    if [ "${#fetch_execution_arguments[@]}" -ne 7 ]; then
+        fail_java_api_fetch_projection_test "Java API fetch execution at index $java_api_source_index must receive exactly seven fields"
+    fi
+
+    actual_fetch_projection="$(IFS='|'; printf '%s' "${fetch_execution_arguments[*]}")"
+    if [ "$actual_fetch_projection" != "$documentation_fetch_projection" ]; then
+        fail_java_api_fetch_projection_test "Java API fetch execution at index $java_api_source_index diverged from the appended projection"
+    fi
+
+    expected_allow_partial="${manifest_projection##*|}"
+    manifest_projection_without_allow_partial="${manifest_projection%|*}"
+    expected_reject_regex="${manifest_projection_without_allow_partial##*|}"
+    if [ "${fetch_execution_arguments[5]}" != "$expected_reject_regex" ]; then
+        fail_java_api_fetch_projection_test "Java API reject regex at index $java_api_source_index was not projected separately"
+    fi
+    if [ "${fetch_execution_arguments[6]}" != "$expected_allow_partial" ]; then
+        fail_java_api_fetch_projection_test "Java API partial-mirror policy at index $java_api_source_index was not projected separately"
+    fi
+done
+
+printf 'PASS: Java API fetch projections retain seven distinct fields in manifest order.\n'

From f9f71b104de4bb6397fb2f66b35e93140ba4f205 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:30:17 -0700
Subject: [PATCH 11/40] test(ingestion): assert partial mirror policy behavior

The projection parity test proved the seventh field survived manifest
projection but never exercised what the flag does, leaving the
partial-mirror branch of validate_fetch_result and the pre-fetch
quarantine guard in fetch_docs without behavioral coverage.

Drive both policies directly: assert allowPartial=true keeps a validated
below-minimum mirror while allowPartial=false rejects it, and that
fetch_docs quarantines an incomplete mirror only when partial mirrors are
disallowed. Use a mktemp docs root with an EXIT trap so the test leaves no
artifacts behind.

- Add validate_fetch_result true/false assertions for below-minimum counts
- Add fetch_docs quarantine assertions gated on the partial-mirror policy
- Replace the hardcoded docs root with a self-cleaning mktemp directory
---
 scripts/test_java_api_fetch_projection.sh | 47 +++++++++++++++++++++--
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index d7e2c696..27767efb 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -8,7 +8,8 @@ TEST_SCRIPT_DIRECTORY="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$TEST_SCRIPT_DIRECTORY/.." && pwd)"
 FETCH_SCRIPT="$PROJECT_ROOT/scripts/fetch_all_docs.sh"
 JAVA_API_SOURCES_MANIFEST="$PROJECT_ROOT/src/main/resources/java-api-documentation-sources.manifest"
-TEST_DOCS_ROOT="/canonical-test-docs"
+TEST_DOCS_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TEST_DOCS_ROOT"' EXIT
 
 fail_java_api_fetch_projection_test() {
     local failure_message="$1"
@@ -16,11 +17,9 @@ fail_java_api_fetch_projection_test() {
     exit 1
 }
 
-test_script_arguments=("$@")
 set --
 # shellcheck source=fetch_all_docs.sh
 source "$FETCH_SCRIPT"
-set -- "${test_script_arguments[@]}"
 
 log() {
     :
@@ -70,4 +69,44 @@ for java_api_source_index in "${!JAVA_API_SOURCE_PROJECTIONS[@]}"; do
     fi
 done
 
-printf 'PASS: Java API fetch projections retain seven distinct fields in manifest order.\n'
+set --
+# shellcheck source=fetch_all_docs.sh
+source "$FETCH_SCRIPT"
+
+log() {
+    :
+}
+
+count_html_files() {
+    printf '5\n'
+}
+
+if ! validate_fetch_result 0 "$TEST_DOCS_ROOT/partial" "Partial mirror" 10 true; then
+    fail_java_api_fetch_projection_test "allowPartial=true rejected a validated below-minimum mirror"
+fi
+if validate_fetch_result 0 "$TEST_DOCS_ROOT/complete-required" "Complete mirror" 10 false; then
+    fail_java_api_fetch_projection_test "allowPartial=false accepted a below-minimum mirror"
+fi
+
+quarantine_capture_file="$TEST_DOCS_ROOT/quarantine.log"
+quarantine_incomplete_dir() {
+    printf 'quarantined\n' >> "$quarantine_capture_file"
+}
+fetch_docs_mirror() {
+    return 0
+}
+
+if ! (fetch_docs "https://example.com/api/" "$TEST_DOCS_ROOT/partial" "Partial mirror" 1 10 "" true); then
+    fail_java_api_fetch_projection_test "allowPartial=true fetch dispatch failed"
+fi
+if [ -s "$quarantine_capture_file" ]; then
+    fail_java_api_fetch_projection_test "allowPartial=true quarantined an incremental mirror"
+fi
+if ! (fetch_docs "https://example.com/api/" "$TEST_DOCS_ROOT/complete-required" "Complete mirror" 1 10 "" false); then
+    fail_java_api_fetch_projection_test "allowPartial=false fetch dispatch failed"
+fi
+if [ ! -s "$quarantine_capture_file" ]; then
+    fail_java_api_fetch_projection_test "allowPartial=false did not quarantine an incomplete mirror"
+fi
+
+printf 'PASS: Java API fetch projections retain all fields and enforce partial-mirror policy.\n'

From 287def4c5f7daf42d2a97818ca43e101216f1fb1 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:31:17 -0700
Subject: [PATCH 12/40] fix(security): keep CSRF protection stateless

Replace the session-coupled CSRF repository with Spring Security's cookie repository so valid cookie/header tokens survive stateless requests. Keep the browser-visible token lifetime and consistent JSON denial response on the verified framework boundary.

- Configure SameSite and max-age through the cookie customizer
- Remove server-session token metadata and expiry branching
- Cover stateless success and missing-token failure through MockMvc
---
 .../web/security/CsrfAccessDeniedHandler.java |  27 ++-
 .../ExpiringCookieCsrfTokenRepository.java    | 157 ------------------
 .../javachat/config/SecurityConfig.java       |  11 +-
 .../javachat/config/SecurityConfigTest.java   |  92 ++++++++++
 4 files changed, 107 insertions(+), 180 deletions(-)
 delete mode 100644 src/main/java/com/williamcallahan/javachat/adapters/in/web/security/ExpiringCookieCsrfTokenRepository.java
 create mode 100644 src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java

diff --git a/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/CsrfAccessDeniedHandler.java b/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/CsrfAccessDeniedHandler.java
index d01c6727..43d773c8 100644
--- a/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/CsrfAccessDeniedHandler.java
+++ b/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/CsrfAccessDeniedHandler.java
@@ -13,13 +13,9 @@
 import org.springframework.security.web.access.AccessDeniedHandler;
 
 /**
- * Returns JSON 403 responses with clear CSRF expiry messaging for API callers.
- *
- * <p>Uses request attributes set by the expiring CSRF repository to distinguish
- * expired tokens from other CSRF failures.</p>
+ * Returns JSON 403 responses with clear invalid-CSRF messaging for API callers.
  */
 public final class CsrfAccessDeniedHandler implements AccessDeniedHandler {
-    private static final String CSRF_EXPIRED_MESSAGE = "CSRF token expired. Refresh the page and retry the request.";
     private static final String CSRF_INVALID_MESSAGE =
             "CSRF token missing or invalid. Refresh the page and retry the request.";
 
@@ -37,27 +33,26 @@ public CsrfAccessDeniedHandler(ObjectMapper objectMapper) {
     /**
      * Writes a JSON 403 response tailored for CSRF failures.
      *
-     * @param request incoming HTTP request
-     * @param response outgoing HTTP response
+     * @param httpRequest incoming HTTP request
+     * @param httpResponse outgoing HTTP response
      * @param accessDeniedException access denied exception from Spring Security
      * @throws IOException when the response cannot be written
      * @throws ServletException when the servlet container rejects the write
      */
     @Override
     public void handle(
-            HttpServletRequest request, HttpServletResponse response, AccessDeniedException accessDeniedException)
+            HttpServletRequest httpRequest,
+            HttpServletResponse httpResponse,
+            AccessDeniedException accessDeniedException)
             throws IOException, ServletException {
-        if (response.isCommitted()) {
+        if (httpResponse.isCommitted()) {
             return;
         }
 
-        boolean csrfExpired =
-                Boolean.TRUE.equals(request.getAttribute(ExpiringCookieCsrfTokenRepository.EXPIRED_ATTRIBUTE));
-        String message = csrfExpired ? CSRF_EXPIRED_MESSAGE : CSRF_INVALID_MESSAGE;
-        ApiErrorResponse payload = ApiErrorResponse.error(message);
+        ApiErrorResponse csrfError = ApiErrorResponse.error(CSRF_INVALID_MESSAGE);
 
-        response.setStatus(HttpStatus.FORBIDDEN.value());
-        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
-        objectMapper.writeValue(response.getOutputStream(), payload);
+        httpResponse.setStatus(HttpStatus.FORBIDDEN.value());
+        httpResponse.setContentType(MediaType.APPLICATION_JSON_VALUE);
+        objectMapper.writeValue(httpResponse.getOutputStream(), csrfError);
     }
 }
diff --git a/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/ExpiringCookieCsrfTokenRepository.java b/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/ExpiringCookieCsrfTokenRepository.java
deleted file mode 100644
index b7d835f3..00000000
--- a/src/main/java/com/williamcallahan/javachat/adapters/in/web/security/ExpiringCookieCsrfTokenRepository.java
+++ /dev/null
@@ -1,157 +0,0 @@
-package com.williamcallahan.javachat.adapters.in.web.security;
-
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.servlet.http.HttpServletResponse;
-import jakarta.servlet.http.HttpSession;
-import java.time.Clock;
-import java.time.Duration;
-import java.util.Objects;
-import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
-import org.springframework.security.web.csrf.CsrfToken;
-import org.springframework.security.web.csrf.CsrfTokenRepository;
-
-/**
- * Stores CSRF tokens in cookies while enforcing a fixed lifetime backed by the servlet session.
- *
- * <p>Uses the cookie repository for token transport while tracking the issued timestamp in the
- * session so tokens expire after a bounded TTL instead of living for the entire session.</p>
- */
-public final class ExpiringCookieCsrfTokenRepository implements CsrfTokenRepository {
-    /**
-     * Request attribute set when an expired token is detected so handlers can surface a clear message.
-     */
-    public static final String EXPIRED_ATTRIBUTE = ExpiringCookieCsrfTokenRepository.class.getName() + ".EXPIRED";
-
-    private static final String SESSION_TOKEN_KEY = ExpiringCookieCsrfTokenRepository.class.getName() + ".TOKEN";
-    private static final String SESSION_ISSUED_AT_KEY =
-            ExpiringCookieCsrfTokenRepository.class.getName() + ".ISSUED_AT";
-
-    private final CookieCsrfTokenRepository delegate;
-    private final Duration tokenTtl;
-    private final Clock clock;
-
-    /**
-     * Creates a repository that expires CSRF tokens after the supplied TTL.
-     *
-     * @param delegate cookie-backed token repository
-     * @param tokenTtl token lifetime for session-bound validation
-     */
-    public ExpiringCookieCsrfTokenRepository(CookieCsrfTokenRepository delegate, Duration tokenTtl) {
-        this(delegate, tokenTtl, Clock.systemUTC());
-    }
-
-    ExpiringCookieCsrfTokenRepository(CookieCsrfTokenRepository delegate, Duration tokenTtl, Clock clock) {
-        this.delegate = Objects.requireNonNull(delegate, "delegate");
-        this.tokenTtl = Objects.requireNonNull(tokenTtl, "tokenTtl");
-        if (tokenTtl.isZero() || tokenTtl.isNegative()) {
-            throw new IllegalArgumentException("tokenTtl must be positive");
-        }
-        this.clock = Objects.requireNonNull(clock, "clock");
-    }
-
-    /**
-     * Generates a new CSRF token using the delegate repository.
-     *
-     * @param request incoming HTTP request
-     * @return newly generated CSRF token
-     */
-    @Override
-    public CsrfToken generateToken(HttpServletRequest request) {
-        return delegate.generateToken(request);
-    }
-
-    /**
-     * Persists the CSRF token in the response cookie and tracks its issue time in the session.
-     *
-     * @param token CSRF token to store, or null to delete
-     * @param request incoming HTTP request
-     * @param response outgoing HTTP response
-     */
-    @Override
-    public void saveToken(CsrfToken token, HttpServletRequest request, HttpServletResponse response) {
-        if (token == null) {
-            clearSessionMetadata(request);
-            delegate.saveToken(null, request, response);
-            return;
-        }
-
-        HttpSession session = request.getSession(true);
-        session.setAttribute(SESSION_TOKEN_KEY, token.getToken());
-        session.setAttribute(SESSION_ISSUED_AT_KEY, clock.millis());
-        delegate.saveToken(token, request, response);
-    }
-
-    /**
-     * Loads the CSRF token when present and rejects it when the session metadata is expired.
-     *
-     * @param request incoming HTTP request
-     * @return CSRF token if valid, otherwise null to force re-issuance
-     */
-    @Override
-    public CsrfToken loadToken(HttpServletRequest request) {
-        CsrfToken token = delegate.loadToken(request);
-        if (token == null) {
-            return null;
-        }
-
-        HttpSession session = request.getSession(false);
-        if (session == null) {
-            return null;
-        }
-
-        String sessionToken = readSessionToken(session);
-        Long issuedAtMillis = readIssuedAtMillis(session);
-        if (sessionToken == null || issuedAtMillis == null) {
-            return null;
-        }
-
-        if (!sessionToken.equals(token.getToken())) {
-            return null;
-        }
-
-        long nowMillis = clock.millis();
-        if (isExpired(nowMillis, issuedAtMillis)) {
-            markExpired(request);
-            return null;
-        }
-
-        return token;
-    }
-
-    private boolean isExpired(long nowMillis, long issuedAtMillis) {
-        long ageMillis = nowMillis - issuedAtMillis;
-        return ageMillis > tokenTtl.toMillis();
-    }
-
-    private void clearSessionMetadata(HttpServletRequest request) {
-        HttpSession session = request.getSession(false);
-        if (session == null) {
-            return;
-        }
-        session.removeAttribute(SESSION_TOKEN_KEY);
-        session.removeAttribute(SESSION_ISSUED_AT_KEY);
-    }
-
-    private String readSessionToken(HttpSession session) {
-        Object attribute = session.getAttribute(SESSION_TOKEN_KEY);
-        if (attribute instanceof String tokenText && !tokenText.isBlank()) {
-            return tokenText;
-        }
-        return null;
-    }
-
-    private Long readIssuedAtMillis(HttpSession session) {
-        Object attribute = session.getAttribute(SESSION_ISSUED_AT_KEY);
-        if (attribute instanceof Long issuedAtMillis) {
-            return issuedAtMillis;
-        }
-        if (attribute instanceof Number issuedAtNumber) {
-            return issuedAtNumber.longValue();
-        }
-        return null;
-    }
-
-    private void markExpired(HttpServletRequest request) {
-        request.setAttribute(EXPIRED_ATTRIBUTE, Boolean.TRUE);
-    }
-}
diff --git a/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java b/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
index 2532999b..8d1eef7d 100644
--- a/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
+++ b/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
@@ -3,7 +3,6 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.williamcallahan.javachat.adapters.in.web.security.CsrfAccessDeniedHandler;
 import com.williamcallahan.javachat.adapters.in.web.security.CsrfTokenCookieFilter;
-import com.williamcallahan.javachat.adapters.in.web.security.ExpiringCookieCsrfTokenRepository;
 import java.time.Duration;
 import java.util.List;
 import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
@@ -32,7 +31,7 @@ public class SecurityConfig {
     private static final String LIVENESS_ENDPOINT = "/actuator/health/liveness";
     private static final String READINESS_ENDPOINT = "/actuator/health/readiness";
     private static final String PROMETHEUS_ENDPOINT = "/actuator/prometheus";
-    private static final long CSRF_TOKEN_TTL_MINUTES = 15L;
+    private static final Duration CSRF_COOKIE_MAX_AGE = Duration.ofMinutes(15L);
 
     /**
      * CORS configuration source for Spring Security filter chain integration.
@@ -89,11 +88,9 @@ public SecurityFilterChain managementSecurityFilterChain(
     public SecurityFilterChain appSecurityFilterChain(
             HttpSecurity http, CorsConfigurationSource corsConfigurationSource, ObjectMapper objectMapper)
             throws Exception {
-        CookieCsrfTokenRepository cookieRepository = CookieCsrfTokenRepository.withHttpOnlyFalse();
-        cookieRepository.setCookieCustomizer(cookie -> cookie.sameSite("Lax"));
-        Duration csrfTokenTtl = Duration.ofMinutes(CSRF_TOKEN_TTL_MINUTES);
-        ExpiringCookieCsrfTokenRepository csrfTokenRepository =
-                new ExpiringCookieCsrfTokenRepository(cookieRepository, csrfTokenTtl);
+        CookieCsrfTokenRepository csrfTokenRepository = CookieCsrfTokenRepository.withHttpOnlyFalse();
+        csrfTokenRepository.setCookieCustomizer(
+                csrfCookie -> csrfCookie.sameSite("Lax").maxAge(CSRF_COOKIE_MAX_AGE));
         CsrfTokenRequestAttributeHandler requestHandler = new CsrfTokenRequestAttributeHandler();
         CsrfAccessDeniedHandler accessDeniedHandler = new CsrfAccessDeniedHandler(objectMapper);
 
diff --git a/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
new file mode 100644
index 00000000..812b1787
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
@@ -0,0 +1,92 @@
+package com.williamcallahan.javachat.config;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import com.williamcallahan.javachat.web.CsrfController;
+import jakarta.servlet.http.Cookie;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Verifies that the browser-readable CSRF cookie remains valid across stateless requests.
+ */
+@WebMvcTest(controllers = CsrfController.class)
+@Import({AppProperties.class, SecurityConfig.class, SecurityConfigTest.ProtectedPostController.class})
+class SecurityConfigTest {
+    private static final String CSRF_REFRESH_ENDPOINT = "/api/security/csrf";
+    private static final String CSRF_PROTECTED_ENDPOINT = "/api/security/csrf-test";
+    private static final String CSRF_COOKIE_NAME = "XSRF-TOKEN";
+    private static final String CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+    private static final int CSRF_COOKIE_MAX_AGE_SECONDS = 900;
+    private static final String CSRF_COOKIE_SAME_SITE_POLICY = "Lax";
+    private static final String CSRF_INVALID_MESSAGE =
+            "CSRF token missing or invalid. Refresh the page and retry the request.";
+
+    @Autowired
+    MockMvc mockMvc;
+
+    @Test
+    void acceptsCookieAndHeaderTokenWithoutServerSession() throws Exception {
+        MvcResult csrfRefreshExchange = mockMvc.perform(get(CSRF_REFRESH_ENDPOINT))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        Cookie csrfCookie = csrfRefreshExchange.getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(csrfCookie);
+        assertEquals(CSRF_COOKIE_MAX_AGE_SECONDS, csrfCookie.getMaxAge());
+        assertEquals(CSRF_COOKIE_SAME_SITE_POLICY, csrfCookie.getAttribute("SameSite"));
+        assertFalse(csrfCookie.isHttpOnly());
+        assertNull(csrfRefreshExchange.getRequest().getSession(false));
+        assertNull(csrfRefreshExchange.getResponse().getCookie("JSESSIONID"));
+
+        MvcResult protectedPostExchange = mockMvc.perform(post(CSRF_PROTECTED_ENDPOINT)
+                        .cookie(csrfCookie)
+                        .header(CSRF_HEADER_NAME, csrfCookie.getValue()))
+                .andExpect(status().isNoContent())
+                .andReturn();
+
+        assertNull(protectedPostExchange.getRequest().getSession(false));
+        assertNull(protectedPostExchange.getResponse().getCookie("JSESSIONID"));
+    }
+
+    @Test
+    void returnsJsonWhenCsrfTokenIsMissing() throws Exception {
+        mockMvc.perform(post(CSRF_PROTECTED_ENDPOINT))
+                .andExpect(status().isForbidden())
+                .andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_JSON))
+                .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
+    }
+
+    /**
+     * Exposes a harmless state-changing route so the real security filter chain can be tested.
+     */
+    @RestController
+    public static final class ProtectedPostController {
+
+        /**
+         * Confirms that Spring Security admitted a state-changing request.
+         *
+         * @return an empty success response
+         */
+        @PostMapping(CSRF_PROTECTED_ENDPOINT)
+        public ResponseEntity<Void> acceptProtectedPost() {
+            return ResponseEntity.noContent().build();
+        }
+    }
+}

From f204efce04b7dd86726f9a639811027aafbabaef Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:33:06 -0700
Subject: [PATCH 13/40] fix(ingestion): isolate manifest fetch execution

---
 scripts/fetch_all_docs.sh                     | 85 +++++++++++--------
 scripts/test_java_api_fetch_projection.sh     | 17 ++++
 .../JavaApiDocumentationSourceParityTest.java | 11 +++
 3 files changed, 76 insertions(+), 37 deletions(-)

diff --git a/scripts/fetch_all_docs.sh b/scripts/fetch_all_docs.sh
index e6fe0595..94b1fbc3 100755
--- a/scripts/fetch_all_docs.sh
+++ b/scripts/fetch_all_docs.sh
@@ -4,8 +4,6 @@
 # This script fetches all required documentation (configured Java APIs, Spring ecosystem)
 # and ensures no redundant downloads by checking existing files
 
-set -euo pipefail
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # shellcheck source=lib/shell_bootstrap.sh
@@ -18,9 +16,6 @@ source "$SCRIPT_DIR/lib/documentation_sources.sh"
 # Centralized source definitions
 RES_PROPS="$SCRIPT_DIR/../src/main/resources/docs-sources.properties"
 JAVA_API_SOURCES_MANIFEST="$SCRIPT_DIR/../src/main/resources/java-api-documentation-sources.manifest"
-if [ -f "$RES_PROPS" ]; then
-  preserve_process_env_then_source_file "$RES_PROPS"
-fi
 DOCS_ROOT="$SCRIPT_DIR/../data/docs"
 LOG_FILE="$SCRIPT_DIR/../fetch_all_docs.log"
 
@@ -29,35 +24,39 @@ INCLUDE_QUICK="${INCLUDE_QUICK:-false}"
 CLEAN_INCOMPLETE="${CLEAN_INCOMPLETE:-true}"
 FORCE_REFRESH="${FORCE_REFRESH:-false}"
 LIST_JAVA_API_SOURCES="false"
-for arg in "$@"; do
-    case $arg in
-        --include-quick)
-            INCLUDE_QUICK="true"
-            ;;
-        --no-clean)
-            CLEAN_INCOMPLETE="false"
-            ;;
-        --force)
-            FORCE_REFRESH="true"
-            ;;
-        --list-java-api-sources)
-            LIST_JAVA_API_SOURCES="true"
-            ;;
-        --help|-h)
-            echo "Usage: $0 [--include-quick] [--no-clean] [--force] [--list-java-api-sources]"
-            echo "  --include-quick : Also refresh small 'quick' doc mirrors"
-            echo "  --no-clean      : Do not quarantine incomplete mirrors before refetch"
-            echo "  --force         : Refresh even when mirrors look complete"
-            echo "  --list-java-api-sources : Print canonical Java API source projections without fetching"
-            exit 0
-            ;;
-        *)
-            echo "Unknown option: $arg"
-            echo "Use --help for usage information"
-            exit 1
-            ;;
-    esac
-done
+
+parse_fetch_arguments() {
+    local fetch_argument
+    for fetch_argument in "$@"; do
+        case $fetch_argument in
+            --include-quick)
+                INCLUDE_QUICK="true"
+                ;;
+            --no-clean)
+                CLEAN_INCOMPLETE="false"
+                ;;
+            --force)
+                FORCE_REFRESH="true"
+                ;;
+            --list-java-api-sources)
+                LIST_JAVA_API_SOURCES="true"
+                ;;
+            --help|-h)
+                echo "Usage: $0 [--include-quick] [--no-clean] [--force] [--list-java-api-sources]"
+                echo "  --include-quick : Also refresh small 'quick' doc mirrors"
+                echo "  --no-clean      : Do not quarantine incomplete mirrors before refetch"
+                echo "  --force         : Refresh even when mirrors look complete"
+                echo "  --list-java-api-sources : Print canonical Java API source projections without fetching"
+                exit 0
+                ;;
+            *)
+                echo "Unknown option: $fetch_argument"
+                echo "Use --help for usage information"
+                exit 1
+                ;;
+        esac
+    done
+}
 
 extract_meta_version() {
     local file_path="$1"
@@ -178,7 +177,10 @@ validate_fetch_result() {
         return 1
     fi
 
-    log "${GREEN}✓ $name fetched successfully: $fetched_html_count HTML files${NC}"
+    if [ "$fetched_html_count" -eq 0 ]; then
+        log "${RED}✗ $name fetch produced no HTML files${NC}"
+        return 1
+    fi
     if [ "$min_files" -gt 0 ] && [ "$fetched_html_count" -lt "$min_files" ]; then
         if [ "$partial_mirror_allowed" = "true" ]; then
             log "${YELLOW}⚠ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+); keeping partial mirror for incremental reruns${NC}"
@@ -187,6 +189,7 @@ validate_fetch_result() {
             return 1
         fi
     fi
+    log "${GREEN}✓ $name fetched successfully: $fetched_html_count HTML files${NC}"
     return 0
 }
 
@@ -385,9 +388,12 @@ fetch_documentation_source() {
     fetch_docs "$documentation_source_url" "$mirror_directory" "$documentation_source_name" "$cut_directories" "$minimum_html_files" "$reject_regex" "$partial_mirror_allowed"
 }
 
-if [[ "${BASH_SOURCE[0]}" != "$0" ]]; then
-    return 0
+run_documentation_fetch() {
+set -euo pipefail
+if [ -f "$RES_PROPS" ]; then
+    preserve_process_env_then_source_file "$RES_PROPS"
 fi
+parse_fetch_arguments "$@"
 
 # Documentation sources configuration
 # Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX|ALLOW_PARTIAL
@@ -528,3 +534,8 @@ if [ "$TOTAL_FAILED" -gt 0 ]; then
     exit 1
 fi
 echo "Next step: Run 'make run' or './scripts/process_all_to_qdrant.sh' to process and upload to Qdrant"
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    run_documentation_fetch "$@"
+fi
diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index 27767efb..80ddcc5d 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -47,6 +47,15 @@ for java_api_source_index in "${!JAVA_API_SOURCE_PROJECTIONS[@]}"; do
         fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index must contain exactly seven fields"
     fi
 
+    manifest_projection_without_release="${manifest_projection#*|}"
+    expected_remote_base_url="${manifest_projection_without_release%%|*}"
+    manifest_projection_after_remote_base_url="${manifest_projection_without_release#*|}"
+    expected_relative_mirror_path="${manifest_projection_after_remote_base_url%%|*}"
+    expected_fetch_projection="$expected_remote_base_url|$TEST_DOCS_ROOT/$expected_relative_mirror_path|${manifest_projection_after_remote_base_url#*|}"
+    if [ "$documentation_fetch_projection" != "$expected_fetch_projection" ]; then
+        fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index diverged from the canonical manifest row"
+    fi
+
     fetch_execution_arguments=()
     fetch_documentation_source "$documentation_fetch_projection" > /dev/null
     if [ "${#fetch_execution_arguments[@]}" -ne 7 ]; then
@@ -77,6 +86,14 @@ log() {
     :
 }
 
+count_html_files() {
+    printf '0\n'
+}
+
+if validate_fetch_result 0 "$TEST_DOCS_ROOT/empty-partial" "Empty partial mirror" 10 true; then
+    fail_java_api_fetch_projection_test "allowPartial=true accepted an empty mirror"
+fi
+
 count_html_files() {
     printf '5\n'
 }
diff --git a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
index 0151426a..5b6ac615 100644
--- a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
+++ b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
@@ -53,5 +53,16 @@ void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOExce
                 .toList();
         assertEquals(manifestSourceRows, actualJavaProjections);
         assertEquals(manifestSourceRows, actualScriptProjections);
+
+        Path fetchProjectionTestPath =
+                Path.of("scripts", "test_java_api_fetch_projection.sh").toAbsolutePath();
+        ProcessBuilder fetchProjectionTestCommand = new ProcessBuilder("/bin/bash", fetchProjectionTestPath.toString());
+        fetchProjectionTestCommand.redirectErrorStream(true);
+        Process fetchProjectionTestProcess = fetchProjectionTestCommand.start();
+        String fetchProjectionTestOutput =
+                new String(fetchProjectionTestProcess.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
+        int fetchProjectionTestExitCode = fetchProjectionTestProcess.waitFor();
+
+        assertEquals(0, fetchProjectionTestExitCode, fetchProjectionTestOutput);
     }
 }

From 6ab46824d65fc05785cac08ad9ac24975afab31c Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:40:16 -0700
Subject: [PATCH 14/40] test(ingestion): cover oracle javadoc partial mirror
 dispatch

The projection test exercised the generic mirror path but left the Oracle
Javadoc branch unverified, so a regression that dropped the partial-mirror
policy while dispatching Oracle seeds or validating their fetch result
would have gone unnoticed.

Assert that fetch_docs forwards the partial-mirror policy to
fetch_oracle_javadoc_seed, and that fetch_oracle_javadoc_seed in turn hands
it to validate_fetch_result, by stubbing each boundary and capturing the
propagated flag.

- Capture the policy forwarded into fetch_oracle_javadoc_seed via fetch_docs
- Capture the policy fetch_oracle_javadoc_seed forwards to validate_fetch_result
---
 scripts/test_java_api_fetch_projection.sh | 49 +++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index 80ddcc5d..f7cbe63c 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -126,4 +126,53 @@ if [ ! -s "$quarantine_capture_file" ]; then
     fail_java_api_fetch_projection_test "allowPartial=false did not quarantine an incomplete mirror"
 fi
 
+oracle_dispatch_capture_file="$TEST_DOCS_ROOT/oracle-dispatch-policy"
+fetch_oracle_javadoc_seed() {
+    printf '%s\n' "$6" > "$oracle_dispatch_capture_file"
+}
+if ! (fetch_docs \
+    "https://docs.oracle.com/en/java/javase/21/docs/api/" \
+    "$TEST_DOCS_ROOT/oracle-dispatch" \
+    "Java 21 API" \
+    5 \
+    10 \
+    "" \
+    true); then
+    fail_java_api_fetch_projection_test "Oracle Javadoc fetch dispatch failed"
+fi
+if [ "$(cat "$oracle_dispatch_capture_file")" != "true" ]; then
+    fail_java_api_fetch_projection_test "Oracle Javadoc dispatch dropped the partial-mirror policy"
+fi
+
+set --
+# shellcheck source=fetch_all_docs.sh
+source "$FETCH_SCRIPT"
+
+LOG_FILE="$TEST_DOCS_ROOT/oracle-seed-fetch.log"
+oracle_validation_capture_file="$TEST_DOCS_ROOT/oracle-validation-policy"
+python3() {
+    : > "$5"
+}
+wget() {
+    return 0
+}
+validate_fetch_result() {
+    printf '%s\n' "$5" > "$oracle_validation_capture_file"
+}
+
+mkdir -p "$TEST_DOCS_ROOT/oracle-validation"
+if ! (cd "$TEST_DOCS_ROOT/oracle-validation" \
+    && fetch_oracle_javadoc_seed \
+        "https://docs.oracle.com/en/java/javase/21/docs/api/" \
+        "$TEST_DOCS_ROOT/oracle-validation" \
+        "Java 21 API" \
+        5 \
+        10 \
+        true); then
+    fail_java_api_fetch_projection_test "Oracle Javadoc validation boundary failed"
+fi
+if [ "$(cat "$oracle_validation_capture_file")" != "true" ]; then
+    fail_java_api_fetch_projection_test "Oracle Javadoc validation dropped the partial-mirror policy"
+fi
+
 printf 'PASS: Java API fetch projections retain all fields and enforce partial-mirror policy.\n'

From 0154de24ff757f1e7b330266121165937b51f733 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:52:20 -0700
Subject: [PATCH 15/40] fix(ingestion): block incomplete documentation runs

Preserve nonempty partial mirrors for incremental retries without reporting
them as completed fetches. Track partial sources separately and fail the
fetch command before Qdrant ingestion until every configured minimum is
satisfied.

Extract metadata emission from the fetch orchestrator so the touched script
retains one orchestration responsibility, and document the resulting
pipeline contract.
---
 docs/pipeline-commands.md                   |  3 +-
 scripts/fetch_all_docs.sh                   | 97 ++++++---------------
 scripts/lib/documentation_fetch_metadata.sh | 73 ++++++++++++++++
 scripts/test_java_api_fetch_projection.sh   | 24 ++++-
 4 files changed, 122 insertions(+), 75 deletions(-)
 create mode 100644 scripts/lib/documentation_fetch_metadata.sh

diff --git a/docs/pipeline-commands.md b/docs/pipeline-commands.md
index 3cd197cb..7d28611b 100644
--- a/docs/pipeline-commands.md
+++ b/docs/pipeline-commands.md
@@ -61,7 +61,8 @@ make fetch-force        # Full: force refetch even if mirrors look complete
 ### What "incremental" means for scraping
 
 - `wget --mirror --timestamping` skips files that haven't changed on the server.
-- Sources with fewer HTML files than their configured minimum are quarantined and re-fetched.
+- Sources with fewer HTML files than their configured minimum are quarantined and re-fetched when `allowPartial=false`.
+- Sources with `allowPartial=true` retain nonempty, below-minimum mirrors for incremental reruns, but the fetch exits nonzero until they reach the configured minimum. Consequently, `make full-pipeline` stops before Qdrant ingestion while any retained mirror remains partial.
 - Oracle Javadoc uses a deterministic Python seed generator (`scripts/oracle_javadoc_seed.py`) to avoid incomplete recursive crawls.
 
 ---
diff --git a/scripts/fetch_all_docs.sh b/scripts/fetch_all_docs.sh
index 94b1fbc3..7b6c597a 100755
--- a/scripts/fetch_all_docs.sh
+++ b/scripts/fetch_all_docs.sh
@@ -12,6 +12,8 @@ source "$SCRIPT_DIR/lib/shell_bootstrap.sh"
 source "$SCRIPT_DIR/lib/env_loader.sh"
 # shellcheck source=lib/documentation_sources.sh
 source "$SCRIPT_DIR/lib/documentation_sources.sh"
+# shellcheck source=lib/documentation_fetch_metadata.sh
+source "$SCRIPT_DIR/lib/documentation_fetch_metadata.sh"
 
 # Centralized source definitions
 RES_PROPS="$SCRIPT_DIR/../src/main/resources/docs-sources.properties"
@@ -24,6 +26,7 @@ INCLUDE_QUICK="${INCLUDE_QUICK:-false}"
 CLEAN_INCOMPLETE="${CLEAN_INCOMPLETE:-true}"
 FORCE_REFRESH="${FORCE_REFRESH:-false}"
 LIST_JAVA_API_SOURCES="false"
+DOCUMENTATION_FETCH_PARTIAL_STATUS=2
 
 parse_fetch_arguments() {
     local fetch_argument
@@ -58,21 +61,6 @@ parse_fetch_arguments() {
     done
 }
 
-extract_meta_version() {
-    local file_path="$1"
-    if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
-        echo ""
-        return 0
-    fi
-    local line
-    line="$(grep -E '<meta name="version" content="[^"]+"' "$file_path" 2>/dev/null | head -n 1 || true)"
-    if [ -z "$line" ]; then
-        echo ""
-        return 0
-    fi
-    echo "$line" | sed -E 's/.*content="([^"]+)".*/\1/'
-}
-
 quarantine_incomplete_dir() {
     local dir="$1"
     local name="$2"
@@ -152,14 +140,15 @@ quarantine_versioned_reference_subdirs() {
 }
 
 # Validates a wget fetch result: checks exit code, counts HTML files, and
-# enforces the minimum-files threshold.  Returns 0 on success, 1 on failure.
+# enforces the minimum-files threshold. Returns 0 on success, 2 for a retained
+# partial mirror, and 1 for any other failure.
 #
 # Arguments:
 #   $1 - wget exit code
 #   $2 - target directory (for HTML count)
 #   $3 - human-readable name
 #   $4 - minimum required HTML files (0 = no minimum)
-#   $5 - whether a validated partial mirror is accepted
+#   $5 - whether a nonempty partial mirror is retained for incremental reruns
 validate_fetch_result() {
     local wget_exit_code="$1"
     local target_dir="$2"
@@ -184,6 +173,7 @@ validate_fetch_result() {
     if [ "$min_files" -gt 0 ] && [ "$fetched_html_count" -lt "$min_files" ]; then
         if [ "$partial_mirror_allowed" = "true" ]; then
             log "${YELLOW}⚠ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+); keeping partial mirror for incremental reruns${NC}"
+            return "$DOCUMENTATION_FETCH_PARTIAL_STATUS"
         else
             log "${RED}✗ $name mirror is still incomplete after fetch: $fetched_html_count HTML files (expected $min_files+)${NC}"
             return 1
@@ -252,7 +242,7 @@ fetch_oracle_javadoc_seed() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
-#   $7 - whether a validated partial mirror is accepted
+#   $7 - whether a nonempty partial mirror is retained for incremental reruns
 fetch_docs_mirror() {
     local url="$1"
     local target_dir="$2"
@@ -307,7 +297,7 @@ fetch_docs_mirror() {
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
 #   $6 - reject regex (optional)
-#   $7 - whether a validated partial mirror is accepted
+#   $7 - whether a nonempty partial mirror is retained for incremental reruns
 fetch_docs() {
     local url="$1"
     local target_dir="$2"
@@ -449,6 +439,7 @@ echo "[$(date)] Starting consolidated documentation fetch" > "$LOG_FILE"
 
 # Statistics
 TOTAL_FETCHED=0
+TOTAL_PARTIAL=0
 TOTAL_FAILED=0
 
 echo ""
@@ -460,8 +451,14 @@ for documentation_source_projection in "${DOC_SOURCES[@]}"; do
     if fetch_documentation_source "$documentation_source_projection"; then
         TOTAL_FETCHED=$((TOTAL_FETCHED + 1))
     else
-        TOTAL_FAILED=$((TOTAL_FAILED + 1))
-        log "${RED}Error: Failed to fetch documentation source; auditing the remaining sources before exit${NC}"
+        documentation_fetch_status=$?
+        if [ "$documentation_fetch_status" -eq "$DOCUMENTATION_FETCH_PARTIAL_STATUS" ]; then
+            TOTAL_PARTIAL=$((TOTAL_PARTIAL + 1))
+            log "${YELLOW}Partial documentation source preserved; completion remains blocked${NC}"
+        else
+            TOTAL_FAILED=$((TOTAL_FAILED + 1))
+            log "${RED}Error: Failed to fetch documentation source; auditing the remaining sources before exit${NC}"
+        fi
     fi
 done
 
@@ -471,66 +468,24 @@ echo "Documentation Fetch Summary"
 echo "=============================================="
 log "📊 Statistics:"
 log "  - Newly fetched: $TOTAL_FETCHED"
+log "  - Partial: $TOTAL_PARTIAL"
 log "  - Failed: $TOTAL_FAILED"
 log "  - Include quick mirrors: $INCLUDE_QUICK"
 log "  - Clean incomplete mirrors: $CLEAN_INCOMPLETE"
 
-# Count total files
-TOTAL_HTML=$(find "$DOCS_ROOT" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')
-TOTAL_FILES=$(find "$DOCS_ROOT" -type f 2>/dev/null | wc -l | tr -d ' ')
-
-SPRING_BOOT_REFERENCE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-boot-complete/reference/index.html")"
-SPRING_FRAMEWORK_REFERENCE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-framework-complete/reference/index.html")"
-SPRING_AI_REFERENCE_STABLE_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference/reference/index.html")"
-SPRING_AI_REFERENCE_2_VERSION="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference-2/reference/2.0/index.html")"
-JAVA_JAVADOC_VERSIONS_METADATA="$(render_java_javadoc_versions_metadata "$DOCS_ROOT")"
-JAVA_COMPLETE_DIRECTORIES_METADATA="$(render_java_complete_directories_metadata "$DOCS_ROOT")"
-
-log "  - Total HTML files: $TOTAL_HTML"
-log "  - Total files: $TOTAL_FILES"
-log "  - Documentation root: $DOCS_ROOT"
-
 echo ""
-if [ "$TOTAL_FAILED" -eq 0 ]; then
-    log "${GREEN}✅ Documentation fetch complete!${NC}"
-else
+if [ "$TOTAL_FAILED" -gt 0 ]; then
     log "${RED}✗ Documentation fetch failed for $TOTAL_FAILED source(s)${NC}"
+elif [ "$TOTAL_PARTIAL" -gt 0 ]; then
+    log "${YELLOW}⚠ Documentation fetch remains partial for $TOTAL_PARTIAL source(s)${NC}"
+else
+    log "${GREEN}✅ Documentation fetch complete!${NC}"
 fi
 log "Check log for details: $LOG_FILE"
 
-# Create a marker file with fetch metadata
-METADATA_FILE="$DOCS_ROOT/.fetch_metadata.json"
-cat > "$METADATA_FILE" << EOF
-{
-  "last_fetch": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "statistics": {
-    "newly_fetched": $TOTAL_FETCHED,
-    "failed": $TOTAL_FAILED,
-    "total_html_files": $TOTAL_HTML,
-    "total_files": $TOTAL_FILES
-  },
-  "versions": {
-$JAVA_JAVADOC_VERSIONS_METADATA,
-    "spring_boot_reference": "$SPRING_BOOT_REFERENCE_VERSION",
-    "spring_framework_reference": "$SPRING_FRAMEWORK_REFERENCE_VERSION",
-    "spring_ai_reference_stable": "$SPRING_AI_REFERENCE_STABLE_VERSION",
-    "spring_ai_reference_2": "$SPRING_AI_REFERENCE_2_VERSION"
-  },
-  "directories": {
-$JAVA_COMPLETE_DIRECTORIES_METADATA,
-    "spring_boot_complete": "$(find "$DOCS_ROOT/spring-boot-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "spring_framework_complete": "$(find "$DOCS_ROOT/spring-framework-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "spring_ai_reference_stable": "$(find "$DOCS_ROOT/spring-ai-reference" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "spring_ai_reference_2": "$(find "$DOCS_ROOT/spring-ai-reference-2" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "spring_ai_api_stable": "$(find "$DOCS_ROOT/spring-ai-api-stable" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
-    "spring_ai_api_2": "$(find "$DOCS_ROOT/spring-ai-api-2" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')"
-  }
-}
-EOF
-
-log "Metadata saved to: $METADATA_FILE"
+write_documentation_fetch_metadata
 echo ""
-if [ "$TOTAL_FAILED" -gt 0 ]; then
+if [ "$TOTAL_FAILED" -gt 0 ] || [ "$TOTAL_PARTIAL" -gt 0 ]; then
     exit 1
 fi
 echo "Next step: Run 'make run' or './scripts/process_all_to_qdrant.sh' to process and upload to Qdrant"
diff --git a/scripts/lib/documentation_fetch_metadata.sh b/scripts/lib/documentation_fetch_metadata.sh
new file mode 100644
index 00000000..7bee049f
--- /dev/null
+++ b/scripts/lib/documentation_fetch_metadata.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+
+# Writes fetch metadata from the completed documentation-fetch run.
+
+extract_meta_version() {
+    local file_path="$1"
+    if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
+        echo ""
+        return 0
+    fi
+    local version_meta_tag
+    version_meta_tag="$(grep -E '<meta name="version" content="[^"]+"' "$file_path" 2>/dev/null | head -n 1 || true)"
+    if [ -z "$version_meta_tag" ]; then
+        echo ""
+        return 0
+    fi
+    echo "$version_meta_tag" | sed -E 's/.*content="([^"]+)".*/\1/'
+}
+
+write_documentation_fetch_metadata() {
+    local total_html_files
+    total_html_files=$(find "$DOCS_ROOT" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')
+    local total_files
+    total_files=$(find "$DOCS_ROOT" -type f 2>/dev/null | wc -l | tr -d ' ')
+    local spring_boot_reference_version
+    spring_boot_reference_version="$(extract_meta_version "$DOCS_ROOT/spring-boot-complete/reference/index.html")"
+    local spring_framework_reference_version
+    spring_framework_reference_version="$(extract_meta_version "$DOCS_ROOT/spring-framework-complete/reference/index.html")"
+    local spring_ai_reference_stable_version
+    spring_ai_reference_stable_version="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference/reference/index.html")"
+    local spring_ai_reference_2_version
+    spring_ai_reference_2_version="$(extract_meta_version "$DOCS_ROOT/spring-ai-reference-2/reference/2.0/index.html")"
+    local java_javadoc_versions_metadata
+    java_javadoc_versions_metadata="$(render_java_javadoc_versions_metadata "$DOCS_ROOT")"
+    local java_complete_directories_metadata
+    java_complete_directories_metadata="$(render_java_complete_directories_metadata "$DOCS_ROOT")"
+
+    log "  - Total HTML files: $total_html_files"
+    log "  - Total files: $total_files"
+    log "  - Documentation root: $DOCS_ROOT"
+
+    local metadata_file="$DOCS_ROOT/.fetch_metadata.json"
+    cat > "$metadata_file" << EOF
+{
+  "last_fetch": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "statistics": {
+    "newly_fetched": $TOTAL_FETCHED,
+    "partial": $TOTAL_PARTIAL,
+    "failed": $TOTAL_FAILED,
+    "total_html_files": $total_html_files,
+    "total_files": $total_files
+  },
+  "versions": {
+$java_javadoc_versions_metadata,
+    "spring_boot_reference": "$spring_boot_reference_version",
+    "spring_framework_reference": "$spring_framework_reference_version",
+    "spring_ai_reference_stable": "$spring_ai_reference_stable_version",
+    "spring_ai_reference_2": "$spring_ai_reference_2_version"
+  },
+  "directories": {
+$java_complete_directories_metadata,
+    "spring_boot_complete": "$(find "$DOCS_ROOT/spring-boot-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+    "spring_framework_complete": "$(find "$DOCS_ROOT/spring-framework-complete" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+    "spring_ai_reference_stable": "$(find "$DOCS_ROOT/spring-ai-reference" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+    "spring_ai_reference_2": "$(find "$DOCS_ROOT/spring-ai-reference-2" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+    "spring_ai_api_stable": "$(find "$DOCS_ROOT/spring-ai-api-stable" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')",
+    "spring_ai_api_2": "$(find "$DOCS_ROOT/spring-ai-api-2" -name "*.html" 2>/dev/null | wc -l | tr -d ' ')"
+  }
+}
+EOF
+
+    log "Metadata saved to: $metadata_file"
+}
diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index f7cbe63c..a66825c6 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -98,13 +98,31 @@ count_html_files() {
     printf '5\n'
 }
 
-if ! validate_fetch_result 0 "$TEST_DOCS_ROOT/partial" "Partial mirror" 10 true; then
-    fail_java_api_fetch_projection_test "allowPartial=true rejected a validated below-minimum mirror"
+partial_validation_status=0
+if validate_fetch_result 0 "$TEST_DOCS_ROOT/partial" "Partial mirror" 10 true; then
+    fail_java_api_fetch_projection_test "allowPartial=true reported a below-minimum mirror as complete"
+else
+    partial_validation_status=$?
+fi
+if [ "$partial_validation_status" -ne "$DOCUMENTATION_FETCH_PARTIAL_STATUS" ]; then
+    fail_java_api_fetch_projection_test "allowPartial=true did not return the partial fetch status"
 fi
 if validate_fetch_result 0 "$TEST_DOCS_ROOT/complete-required" "Complete mirror" 10 false; then
     fail_java_api_fetch_projection_test "allowPartial=false accepted a below-minimum mirror"
 fi
 
+count_html_files() {
+    printf '10\n'
+}
+
+if ! validate_fetch_result 0 "$TEST_DOCS_ROOT/complete-partial-allowed" "Complete partial-allowed mirror" 10 true; then
+    fail_java_api_fetch_projection_test "allowPartial=true rejected a complete mirror"
+fi
+
+count_html_files() {
+    printf '5\n'
+}
+
 quarantine_capture_file="$TEST_DOCS_ROOT/quarantine.log"
 quarantine_incomplete_dir() {
     printf 'quarantined\n' >> "$quarantine_capture_file"
@@ -175,4 +193,4 @@ if [ "$(cat "$oracle_validation_capture_file")" != "true" ]; then
     fail_java_api_fetch_projection_test "Oracle Javadoc validation dropped the partial-mirror policy"
 fi
 
-printf 'PASS: Java API fetch projections retain all fields and enforce partial-mirror policy.\n'
+printf 'PASS: Java API fetch projections preserve partial mirrors without reporting completion.\n'

From f0c2ddba94c8e52d6ec346a459461f5d3b9d01ba Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 12:53:25 -0700
Subject: [PATCH 16/40] test(ingestion): cover partial run exit

---
 scripts/test_java_api_fetch_projection.sh | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index a66825c6..d28aa76b 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -193,4 +193,22 @@ if [ "$(cat "$oracle_validation_capture_file")" != "true" ]; then
     fail_java_api_fetch_projection_test "Oracle Javadoc validation dropped the partial-mirror policy"
 fi
 
+run_summary_capture_file="$TEST_DOCS_ROOT/run-summary"
+LOG_FILE="$TEST_DOCS_ROOT/full-run.log"
+fetch_documentation_source() {
+    return "$DOCUMENTATION_FETCH_PARTIAL_STATUS"
+}
+write_documentation_fetch_metadata() {
+    printf '%s|%s|%s\n' "$TOTAL_FETCHED" "$TOTAL_PARTIAL" "$TOTAL_FAILED" > "$run_summary_capture_file"
+}
+
+if (run_documentation_fetch > /dev/null 2>&1); then
+    fail_java_api_fetch_projection_test "a full fetch run reported success while every source remained partial"
+fi
+
+IFS='|' read -r aggregated_fetched_count aggregated_partial_count aggregated_failed_count < "$run_summary_capture_file"
+if [ "$aggregated_fetched_count" -ne 0 ] || [ "$aggregated_partial_count" -le 0 ] || [ "$aggregated_failed_count" -ne 0 ]; then
+    fail_java_api_fetch_projection_test "a full fetch run did not aggregate retained partial mirrors separately from failures"
+fi
+
 printf 'PASS: Java API fetch projections preserve partial mirrors without reporting completion.\n'

From 8259404ff1d628ac079f7a58b89fa4d81f524ea1 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:32:19 -0700
Subject: [PATCH 17/40] fix(streaming): let request timeout govern SDK reads

Remove the redundant SDK read deadline so provider gateways remain the sole owner of first-output and inter-output timing while the whole request keeps its configured bound.
---
 docs/configuration.md                         |  3 +-
 .../service/OpenAIStreamingService.java       |  4 ---
 src/main/resources/application-dev.properties |  4 +--
 src/main/resources/application.properties     |  4 +--
 .../OpenAIStreamingTimeoutContractTest.java   | 29 +++++++++++++++++++
 5 files changed, 34 insertions(+), 10 deletions(-)
 create mode 100644 src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingTimeoutContractTest.java

diff --git a/docs/configuration.md b/docs/configuration.md
index 2b889dc5..3dfaf6ab 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -27,8 +27,7 @@ Common variables:
 - `OPENAI_BASE_URL` (default `https://api.openai.com/v1`)
 - `OPENAI_MODEL` (application fallback default `gpt-5.2`; shared-gateway alias `gemma-4-26b-a4b`)
 - `OPENAI_REASONING_EFFORT` (optional, GPT‑5 family)
-- `OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS` (default `600`)
-- `OPENAI_STREAMING_READ_TIMEOUT_SECONDS` (default `75`)
+- `OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS` (default `600`; bounds the complete SDK call while provider gateways own first-output and inter-output deadlines)
 
 ### Researchly shared gateway
 
diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
index 1993e576..1763eddf 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAIStreamingService.java
@@ -75,9 +75,6 @@ public class OpenAIStreamingService {
     @Value("${OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS:600}")
     private long streamingRequestTimeoutSeconds;
 
-    @Value("${OPENAI_STREAMING_READ_TIMEOUT_SECONDS:75}")
-    private long streamingReadTimeoutSeconds;
-
     /**
      * LLM-gateway priority class sent as the {@code X-Tier} header on live chat
      * turns. The gateway queue treats untagged requests as {@code default}
@@ -410,7 +407,6 @@ private Flux<String> executeStreamingRequest(
     private Timeout streamingTimeout() {
         return Timeout.builder()
                 .request(Duration.ofSeconds(Math.max(1, streamingRequestTimeoutSeconds)))
-                .read(Duration.ofSeconds(Math.max(1, streamingReadTimeoutSeconds)))
                 .build();
     }
 
diff --git a/src/main/resources/application-dev.properties b/src/main/resources/application-dev.properties
index 65fb3369..1662cde6 100644
--- a/src/main/resources/application-dev.properties
+++ b/src/main/resources/application-dev.properties
@@ -17,8 +17,8 @@ app.clicky.enabled=false
 # Defaults are set via @Value annotations in OpenAIStreamingService.java;
 # override via environment variables GITHUB_MODELS_BASE_URL or OPENAI_BASE_URL.
 # Optional: set OPENAI_REASONING_EFFORT for GPT-5.2 family (e.g., high for gpt-5.2-pro).
-# Streaming timeouts: OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS (default: 600),
-# OPENAI_STREAMING_READ_TIMEOUT_SECONDS (default: 75). All set via env vars.
+# Streaming timeout: OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS (default: 600).
+# Provider gateways own first-output and inter-output timeout policy.
 # Provider ordering: LLM_PRIMARY_PROVIDER=github_models (default) or openai.
 # If both providers are configured, the secondary provider is used as explicit fallback.
 
diff --git a/src/main/resources/application.properties b/src/main/resources/application.properties
index d2b041ee..27c44297 100644
--- a/src/main/resources/application.properties
+++ b/src/main/resources/application.properties
@@ -43,8 +43,8 @@ spring.ai.openai.chat.api-key=${GITHUB_TOKEN:${OPENAI_API_KEY:}}
 # GitHub model IDs should be provider-qualified (for example OPENAI/GPT-5 => openai/gpt-5).
 # OPENAI_MODEL defaults to gpt-5.2 and GITHUB_MODELS_CHAT_MODEL defaults to openai/gpt-5.
 # Optional: set OPENAI_REASONING_EFFORT for GPT-5.2 family (e.g., high for gpt-5.2-pro).
-# Streaming timeouts: OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS (default: 600),
-# OPENAI_STREAMING_READ_TIMEOUT_SECONDS (default: 75). All set via env vars.
+# Streaming timeout: OPENAI_STREAMING_REQUEST_TIMEOUT_SECONDS (default: 600).
+# Provider gateways own first-output and inter-output timeout policy.
 # Provider ordering: LLM_PRIMARY_PROVIDER=github_models (default) or openai.
 # If both providers are configured, the secondary provider is used as explicit fallback.
 
diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingTimeoutContractTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingTimeoutContractTest.java
new file mode 100644
index 00000000..715f2fa2
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingTimeoutContractTest.java
@@ -0,0 +1,29 @@
+package com.williamcallahan.javachat.service;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+
+import com.openai.core.Timeout;
+import com.williamcallahan.javachat.application.streaming.StreamingFailureReporter;
+import java.time.Duration;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+
+/** Verifies that provider gateways remain the sole owner of streaming subphase deadlines. */
+class OpenAIStreamingTimeoutContractTest {
+
+    @Test
+    void streamingReadDeadlineInheritsWholeRequestDeadline() {
+        OpenAIStreamingService streamingService = new OpenAIStreamingService(
+                mock(RateLimitService.class),
+                mock(OpenAiRequestFactory.class),
+                mock(OpenAiProviderRoutingService.class),
+                mock(StreamingFailureReporter.class));
+        ReflectionTestUtils.setField(streamingService, "streamingRequestTimeoutSeconds", 600L);
+
+        Timeout streamingTimeout = ReflectionTestUtils.invokeMethod(streamingService, "streamingTimeout");
+
+        assertEquals(Duration.ofSeconds(600), streamingTimeout.request());
+        assertEquals(streamingTimeout.request(), streamingTimeout.read());
+    }
+}

From 9b4bb5ee78308595b4b638fee6b1831fbc614a60 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:32:37 -0700
Subject: [PATCH 18/40] fix(security): preserve CSRF cookie deletion

Use the framework's stateless session-cookie lifetime so logout can emit an immediate deletion cookie, and cover mismatched and single-sided token rejection.
---
 .../javachat/config/SecurityConfig.java       |  5 +-
 .../javachat/config/SecurityConfigTest.java   | 47 ++++++++++++++++---
 2 files changed, 42 insertions(+), 10 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java b/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
index 8d1eef7d..ba13232e 100644
--- a/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
+++ b/src/main/java/com/williamcallahan/javachat/config/SecurityConfig.java
@@ -3,7 +3,6 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.williamcallahan.javachat.adapters.in.web.security.CsrfAccessDeniedHandler;
 import com.williamcallahan.javachat.adapters.in.web.security.CsrfTokenCookieFilter;
-import java.time.Duration;
 import java.util.List;
 import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
 import org.springframework.context.annotation.Bean;
@@ -31,7 +30,6 @@ public class SecurityConfig {
     private static final String LIVENESS_ENDPOINT = "/actuator/health/liveness";
     private static final String READINESS_ENDPOINT = "/actuator/health/readiness";
     private static final String PROMETHEUS_ENDPOINT = "/actuator/prometheus";
-    private static final Duration CSRF_COOKIE_MAX_AGE = Duration.ofMinutes(15L);
 
     /**
      * CORS configuration source for Spring Security filter chain integration.
@@ -89,8 +87,7 @@ public SecurityFilterChain appSecurityFilterChain(
             HttpSecurity http, CorsConfigurationSource corsConfigurationSource, ObjectMapper objectMapper)
             throws Exception {
         CookieCsrfTokenRepository csrfTokenRepository = CookieCsrfTokenRepository.withHttpOnlyFalse();
-        csrfTokenRepository.setCookieCustomizer(
-                csrfCookie -> csrfCookie.sameSite("Lax").maxAge(CSRF_COOKIE_MAX_AGE));
+        csrfTokenRepository.setCookieCustomizer(csrfCookie -> csrfCookie.sameSite("Lax"));
         CsrfTokenRequestAttributeHandler requestHandler = new CsrfTokenRequestAttributeHandler();
         CsrfAccessDeniedHandler accessDeniedHandler = new CsrfAccessDeniedHandler(objectMapper);
 
diff --git a/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
index 812b1787..11cbe0ed 100644
--- a/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
+++ b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
@@ -31,9 +31,9 @@
 class SecurityConfigTest {
     private static final String CSRF_REFRESH_ENDPOINT = "/api/security/csrf";
     private static final String CSRF_PROTECTED_ENDPOINT = "/api/security/csrf-test";
+    private static final String LOGOUT_ENDPOINT = "/logout";
     private static final String CSRF_COOKIE_NAME = "XSRF-TOKEN";
     private static final String CSRF_HEADER_NAME = "X-XSRF-TOKEN";
-    private static final int CSRF_COOKIE_MAX_AGE_SECONDS = 900;
     private static final String CSRF_COOKIE_SAME_SITE_POLICY = "Lax";
     private static final String CSRF_INVALID_MESSAGE =
             "CSRF token missing or invalid. Refresh the page and retry the request.";
@@ -43,13 +43,9 @@ class SecurityConfigTest {
 
     @Test
     void acceptsCookieAndHeaderTokenWithoutServerSession() throws Exception {
-        MvcResult csrfRefreshExchange = mockMvc.perform(get(CSRF_REFRESH_ENDPOINT))
-                .andExpect(status().isOk())
-                .andReturn();
-
+        MvcResult csrfRefreshExchange = requestCsrfCookie();
         Cookie csrfCookie = csrfRefreshExchange.getResponse().getCookie(CSRF_COOKIE_NAME);
         assertNotNull(csrfCookie);
-        assertEquals(CSRF_COOKIE_MAX_AGE_SECONDS, csrfCookie.getMaxAge());
         assertEquals(CSRF_COOKIE_SAME_SITE_POLICY, csrfCookie.getAttribute("SameSite"));
         assertFalse(csrfCookie.isHttpOnly());
         assertNull(csrfRefreshExchange.getRequest().getSession(false));
@@ -73,6 +69,45 @@ void returnsJsonWhenCsrfTokenIsMissing() throws Exception {
                 .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
     }
 
+    @Test
+    void rejectsMismatchedAndSingleSidedCsrfTokens() throws Exception {
+        Cookie csrfCookie = requestCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(csrfCookie);
+
+        mockMvc.perform(post(CSRF_PROTECTED_ENDPOINT)
+                        .cookie(csrfCookie)
+                        .header(CSRF_HEADER_NAME, csrfCookie.getValue() + "-mismatch"))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
+        mockMvc.perform(post(CSRF_PROTECTED_ENDPOINT).cookie(csrfCookie))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
+        mockMvc.perform(post(CSRF_PROTECTED_ENDPOINT).header(CSRF_HEADER_NAME, csrfCookie.getValue()))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
+    }
+
+    @Test
+    void deletesCsrfCookieImmediatelyOnLogout() throws Exception {
+        Cookie csrfCookie = requestCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(csrfCookie);
+
+        MvcResult logoutExchange = mockMvc.perform(
+                        post(LOGOUT_ENDPOINT).cookie(csrfCookie).header(CSRF_HEADER_NAME, csrfCookie.getValue()))
+                .andExpect(status().is3xxRedirection())
+                .andReturn();
+
+        Cookie deletedCsrfCookie = logoutExchange.getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(deletedCsrfCookie);
+        assertEquals(0, deletedCsrfCookie.getMaxAge());
+    }
+
+    private MvcResult requestCsrfCookie() throws Exception {
+        return mockMvc.perform(get(CSRF_REFRESH_ENDPOINT))
+                .andExpect(status().isOk())
+                .andReturn();
+    }
+
     /**
      * Exposes a harmless state-changing route so the real security filter chain can be tested.
      */

From e474671261dec14c9cec3d0140a04cffde469103 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:32:49 -0700
Subject: [PATCH 19/40] fix(citations): anchor guided PDF chunks before dedupe

Preserve document-to-citation alignment through PDF page estimation, then collapse only citations that resolve to the same final page anchor.
---
 .../service/GuidedLearningService.java        |  68 ++++++++--
 .../GuidedLearningServiceCitationTest.java    | 116 ++++++++++++++++++
 2 files changed, 176 insertions(+), 8 deletions(-)
 create mode 100644 src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java

diff --git a/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java b/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
index cad006b9..364a0813 100644
--- a/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
@@ -14,8 +14,10 @@
 import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Optional;
+import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 import org.slf4j.Logger;
@@ -126,9 +128,7 @@ public List<Citation> citationsForLesson(String slug) {
                     List<Document> retrievedDocuments = retrievalService.retrieve(query);
                     List<Document> bookDocuments = filterToBook(retrievedDocuments);
                     if (bookDocuments.isEmpty()) return List.<Citation>of();
-                    List<Citation> baseCitations =
-                            retrievalService.toCitations(bookDocuments).citations();
-                    return pdfCitationEnhancer.enhanceWithPageAnchors(bookDocuments, baseCitations);
+                    return buildPageAnchoredCitations(bookDocuments);
                 })
                 .orElse(List.of());
     }
@@ -199,15 +199,67 @@ public List<Citation> citationsForBookDocuments(List<Document> bookContextDocume
         if (bookContextDocuments == null || bookContextDocuments.isEmpty()) {
             return List.of();
         }
-        RetrievalService.CitationOutcome citationOutcome = retrievalService.toCitations(bookContextDocuments);
-        if (citationOutcome.failedConversionCount() > 0) {
+        return buildPageAnchoredCitations(bookContextDocuments);
+    }
+
+    /**
+     * Builds page-anchored citations without collapsing distinct source chunks before anchoring.
+     *
+     * <p>Each document is converted independently through the canonical citation converter, then only
+     * successfully converted documents are paired with their citation for page-anchor enhancement. This
+     * preserves the enhancer's one-to-one contract before presentation deduplication operates on final
+     * anchor-bearing URLs.</p>
+     *
+     * @param bookContextDocuments retrieved Think Java documents used to ground a response
+     * @return citations whose PDF URLs include their estimated page anchors
+     */
+    private List<Citation> buildPageAnchoredCitations(List<Document> bookContextDocuments) {
+        List<Document> citationDocuments = new ArrayList<>();
+        List<Citation> citationsBeforePageAnchoring = new ArrayList<>();
+        int failedCitationConversions = 0;
+
+        for (Document bookContextDocument : bookContextDocuments) {
+            if (bookContextDocument == null) {
+                continue;
+            }
+
+            RetrievalService.CitationOutcome singleDocumentCitationOutcome =
+                    retrievalService.toCitations(List.of(bookContextDocument));
+            failedCitationConversions += singleDocumentCitationOutcome.failedConversionCount();
+            for (Citation documentCitation : singleDocumentCitationOutcome.citations()) {
+                citationDocuments.add(bookContextDocument);
+                citationsBeforePageAnchoring.add(documentCitation);
+            }
+        }
+
+        if (failedCitationConversions > 0) {
             logger.warn(
                     "Guided citation conversion had {} failure(s) out of {} documents",
-                    citationOutcome.failedConversionCount(),
+                    failedCitationConversions,
                     bookContextDocuments.size());
         }
-        List<Citation> baseCitations = citationOutcome.citations();
-        return pdfCitationEnhancer.enhanceWithPageAnchors(bookContextDocuments, baseCitations);
+        if (citationDocuments.isEmpty()) {
+            return List.of();
+        }
+        return deduplicateCitationsByAnchoredUrl(
+                pdfCitationEnhancer.enhanceWithPageAnchors(citationDocuments, citationsBeforePageAnchoring));
+    }
+
+    /**
+     * Retains the first citation for each final, page-anchored URL in encounter order.
+     *
+     * @param pageAnchoredCitations citations after their PDF page fragments have been added
+     * @return citations without repeated final URLs
+     */
+    private static List<Citation> deduplicateCitationsByAnchoredUrl(List<Citation> pageAnchoredCitations) {
+        Set<String> retainedAnchoredCitationUrls = new LinkedHashSet<>();
+        List<Citation> deduplicatedPageAnchoredCitations = new ArrayList<>();
+        for (Citation pageAnchoredCitation : pageAnchoredCitations) {
+            if (retainedAnchoredCitationUrls.add(pageAnchoredCitation.getUrl())) {
+                deduplicatedPageAnchoredCitations.add(pageAnchoredCitation);
+            }
+        }
+        return deduplicatedPageAnchoredCitations;
     }
 
     /**
diff --git a/src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java b/src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java
new file mode 100644
index 00000000..ff0c2904
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java
@@ -0,0 +1,116 @@
+package com.williamcallahan.javachat.service;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.williamcallahan.javachat.config.AppProperties;
+import com.williamcallahan.javachat.config.SystemPromptConfig;
+import com.williamcallahan.javachat.model.Citation;
+import com.williamcallahan.javachat.support.PdfCitationEnhancer;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.ai.document.Document;
+
+/**
+ * Verifies guided citations preserve PDF page anchors for independently retrieved book chunks.
+ */
+class GuidedLearningServiceCitationTest {
+    private static final String FIRST_BOOK_CHUNK_ID = "first-book-chunk";
+    private static final int FIRST_BOOK_CHUNK_INDEX = 0;
+    private static final int FIRST_BOOK_CHUNK_PAGE = 1;
+    private static final String LAST_BOOK_CHUNK_ID = "last-book-chunk";
+    private static final String SAME_PAGE_BOOK_CHUNK_ID = "same-page-book-chunk";
+    private static final int SAME_PAGE_BOOK_CHUNK_INDEX = 1;
+    private static final String THINK_JAVA_PDF_URL =
+            "https://example.test/pdfs/Think%20Java%20-%202nd%20Edition%20Book.pdf";
+    private static final String THINK_JAVA_SOURCE_CHUNK_TEXT = "Think Java source chunk";
+    private static final String THINK_JAVA_TITLE = "Think Java";
+    private static final String METADATA_CHUNK_INDEX = "chunkIndex";
+    private static final String METADATA_TITLE = "title";
+    private static final String METADATA_URL = "url";
+    private static final String PDF_PAGE_URL_FRAGMENT_PREFIX = "#page=";
+    private static final String PDF_PAGE_ANCHOR_PREFIX = "page=";
+    private static final String PARSED_CHUNK_SAFE_NAME = "think-java";
+    private static final String PARSED_CHUNK_FILE_PREFIX = PARSED_CHUNK_SAFE_NAME + "_";
+    private static final String PARSED_CHUNK_FILE_SUFFIX = ".txt";
+    private static final int PARSED_CHUNK_FILE_COUNT = 10;
+    private static final int TEST_PDF_PAGE_COUNT = 5;
+    private static final String TEST_JDK_VERSION = "25";
+
+    @Test
+    void citationsForBookDocumentsRetainsDistinctPageAnchorsAndDeduplicatesSamePage(@TempDir Path parsedChunkDirectory)
+            throws IOException {
+        createParsedChunkFiles(parsedChunkDirectory);
+        LocalStoreService localStoreService = mock(LocalStoreService.class);
+        when(localStoreService.toSafeName(THINK_JAVA_PDF_URL)).thenReturn(PARSED_CHUNK_SAFE_NAME);
+        when(localStoreService.getParsedDir()).thenReturn(parsedChunkDirectory);
+        GuidedLearningService guidedLearningService = new GuidedLearningService(
+                mock(GuidedTOCProvider.class),
+                retrievalService(),
+                mock(EnrichmentService.class),
+                mock(ChatService.class),
+                mock(SystemPromptConfig.class),
+                new FixedPagePdfCitationEnhancer(localStoreService, TEST_PDF_PAGE_COUNT),
+                new AppProperties(),
+                TEST_JDK_VERSION);
+
+        List<Citation> pageAnchoredCitations = guidedLearningService.citationsForBookDocuments(List.of(
+                thinkJavaChunk(FIRST_BOOK_CHUNK_ID, FIRST_BOOK_CHUNK_INDEX),
+                thinkJavaChunk(SAME_PAGE_BOOK_CHUNK_ID, SAME_PAGE_BOOK_CHUNK_INDEX),
+                thinkJavaChunk(LAST_BOOK_CHUNK_ID, PARSED_CHUNK_FILE_COUNT - 1)));
+
+        assertEquals(
+                List.of(
+                        THINK_JAVA_PDF_URL + PDF_PAGE_URL_FRAGMENT_PREFIX + FIRST_BOOK_CHUNK_PAGE,
+                        THINK_JAVA_PDF_URL + PDF_PAGE_URL_FRAGMENT_PREFIX + TEST_PDF_PAGE_COUNT),
+                pageAnchoredCitations.stream().map(Citation::getUrl).toList());
+        assertEquals(
+                List.of(PDF_PAGE_ANCHOR_PREFIX + FIRST_BOOK_CHUNK_PAGE, PDF_PAGE_ANCHOR_PREFIX + TEST_PDF_PAGE_COUNT),
+                pageAnchoredCitations.stream().map(Citation::getAnchor).toList());
+    }
+
+    private static RetrievalService retrievalService() {
+        return new RetrievalService(
+                mock(HybridSearchService.class),
+                new AppProperties(),
+                mock(RerankerService.class),
+                mock(DocumentFactory.class));
+    }
+
+    private static void createParsedChunkFiles(Path parsedChunkDirectory) throws IOException {
+        for (int chunkIndex = 0; chunkIndex < PARSED_CHUNK_FILE_COUNT; chunkIndex++) {
+            Files.createFile(
+                    parsedChunkDirectory.resolve(PARSED_CHUNK_FILE_PREFIX + chunkIndex + PARSED_CHUNK_FILE_SUFFIX));
+        }
+    }
+
+    private static Document thinkJavaChunk(String documentId, int chunkIndex) {
+        return Document.builder()
+                .id(documentId)
+                .text(THINK_JAVA_SOURCE_CHUNK_TEXT)
+                .metadata(METADATA_URL, THINK_JAVA_PDF_URL)
+                .metadata(METADATA_TITLE, THINK_JAVA_TITLE)
+                .metadata(METADATA_CHUNK_INDEX, chunkIndex)
+                .build();
+    }
+
+    /** Supplies a deterministic page count while retaining the production anchor calculation. */
+    private static final class FixedPagePdfCitationEnhancer extends PdfCitationEnhancer {
+        private final int pdfPageCount;
+
+        private FixedPagePdfCitationEnhancer(LocalStoreService localStoreService, int pdfPageCount) {
+            super(localStoreService);
+            this.pdfPageCount = pdfPageCount;
+        }
+
+        @Override
+        public int getThinkJavaPdfPages() {
+            return pdfPageCount;
+        }
+    }
+}

From 4f1adc575d4f6f2ca1ca2efe102d29c8ebb8285b Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:33:03 -0700
Subject: [PATCH 20/40] fix(streaming): report SSE transport failures

Invoke the canonical error callback exactly once for non-abort fetch and reader failures while preserving rejection identity and silent cancellation.
---
 frontend/src/lib/services/sse.test.ts | 50 ++++++++++++++++++++++++++-
 frontend/src/lib/services/sse.ts      | 16 ++++++++-
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/frontend/src/lib/services/sse.test.ts b/frontend/src/lib/services/sse.test.ts
index d7a64bd1..b065609b 100644
--- a/frontend/src/lib/services/sse.test.ts
+++ b/frontend/src/lib/services/sse.test.ts
@@ -2,6 +2,8 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { streamSse } from "./sse";
 
 const SSE_STREAM_RESPONSE_STATUS = 200;
+const FETCH_FAILURE_MESSAGE = "Network request failed";
+const STREAM_READ_FAILURE_MESSAGE = "Unable to read the SSE stream";
 
 function createSseStreamResponse(sseWireText: string): Response {
   const encoder = new TextEncoder();
@@ -17,7 +19,7 @@ function createSseStreamResponse(sseWireText: string): Response {
   });
 }
 
-describe("streamSse abort handling", () => {
+describe("streamSse transport handling", () => {
   afterEach(() => {
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
@@ -43,6 +45,24 @@ describe("streamSse abort handling", () => {
     expect(onError).not.toHaveBeenCalled();
   });
 
+  it("reports and rejects a non-abort fetch failure exactly once", async () => {
+    const fetchFailure = new Error(FETCH_FAILURE_MESSAGE);
+    const fetchMock = vi.fn().mockRejectedValue(fetchFailure);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamSse("/api/test/stream", { hello: "world" }, { onText, onError }, "sse.test.ts"),
+    ).rejects.toBe(fetchFailure);
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: FETCH_FAILURE_MESSAGE });
+  });
+
   it("treats AbortError during read as a cancellation (no onError)", async () => {
     const encoder = new TextEncoder();
     const abortError = Object.assign(new Error("Aborted"), { name: "AbortError" });
@@ -72,6 +92,34 @@ describe("streamSse abort handling", () => {
     expect(onText).toHaveBeenCalledWith("Hello");
     expect(onError).not.toHaveBeenCalled();
   });
+
+  it("reports and rejects a stream-read failure exactly once", async () => {
+    const streamReadFailure = new Error(STREAM_READ_FAILURE_MESSAGE);
+    const sseStreamBody = new ReadableStream<Uint8Array>({
+      start(streamController) {
+        streamController.error(streamReadFailure);
+      },
+    });
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(sseStreamBody, {
+        status: SSE_STREAM_RESPONSE_STATUS,
+        statusText: "OK",
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamSse("/api/test/stream", { hello: "world" }, { onText, onError }, "sse.test.ts"),
+    ).rejects.toBe(streamReadFailure);
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: STREAM_READ_FAILURE_MESSAGE });
+  });
 });
 
 describe("streamSse payload validation", () => {
diff --git a/frontend/src/lib/services/sse.ts b/frontend/src/lib/services/sse.ts
index 4b5a46c1..451ec42f 100644
--- a/frontend/src/lib/services/sse.ts
+++ b/frontend/src/lib/services/sse.ts
@@ -46,6 +46,11 @@ function isAbortError(error: unknown): boolean {
   return error instanceof Error && error.name === "AbortError";
 }
 
+function reportSseFailure(callbacks: SseCallbacks, sseFailure: unknown): void {
+  const sseFailureMessage = sseFailure instanceof Error ? sseFailure.message : String(sseFailure);
+  callbacks.onError?.({ message: sseFailureMessage });
+}
+
 function throwInvalidSseEvent(callbacks: SseCallbacks): never {
   const streamError: StreamError = { message: INVALID_SSE_EVENT_MESSAGE };
   callbacks.onError?.(streamError);
@@ -213,6 +218,7 @@ export async function streamSse(
     if (abortSignal?.aborted || isAbortError(fetchError)) {
       return;
     }
+    reportSseFailure(callbacks, fetchError);
     throw fetchError;
   }
 
@@ -237,6 +243,7 @@ export async function streamSseGet(
     if (abortSignal?.aborted || isAbortError(fetchError)) {
       return;
     }
+    reportSseFailure(callbacks, fetchError);
     throw fetchError;
   }
 
@@ -289,7 +296,14 @@ async function consumeSseStream(
 
   try {
     while (true) {
-      const { done: streamEnded, value: byteSegment } = await sseReader.read();
+      const { done: streamEnded, value: byteSegment } = await sseReader
+        .read()
+        .catch((streamReadFailure: unknown): never => {
+          if (!abortSignal?.aborted && !isAbortError(streamReadFailure)) {
+            reportSseFailure(callbacks, streamReadFailure);
+          }
+          throw streamReadFailure;
+        });
 
       if (streamEnded) {
         streamCompletedNormally = true;

From 3392b95bf9239faf7f9a92e6754524bfebe72723 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:33:19 -0700
Subject: [PATCH 21/40] fix(ingestion): remove stale Java quick docsets

Keep every selectable Java documentation set manifest-backed and reject legacy quick tokens that no longer have fetch or citation mappings.
---
 .../javachat/cli/DocumentationSetCatalog.java             | 6 ------
 .../cli/JavaApiDocumentationSourceParityTest.java         | 8 +++++++-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
index e3379bc9..ff9aa402 100644
--- a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
+++ b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSetCatalog.java
@@ -27,10 +27,6 @@ final class DocumentationSetCatalog {
     private static final String DOCSET_SPRING_AI_COMPLETE_NAME = "Spring AI Complete";
     private static final String DOCSET_SPRING_AI_COMPLETE_PATH = "spring-ai-complete";
 
-    private static final String DOCSET_JAVA_24_QUICK_NAME = "Java 24 Quick";
-    private static final String DOCSET_JAVA_24_QUICK_PATH = "java24";
-    private static final String DOCSET_JAVA_25_QUICK_NAME = "Java 25 Quick";
-    private static final String DOCSET_JAVA_25_QUICK_PATH = "java25";
     private static final String DOCSET_SPRING_BOOT_QUICK_NAME = "Spring Boot Quick";
     private static final String DOCSET_SPRING_BOOT_QUICK_PATH = "spring-boot";
     private static final String DOCSET_SPRING_FRAMEWORK_QUICK_NAME = "Spring Framework Quick";
@@ -41,8 +37,6 @@ final class DocumentationSetCatalog {
     private static final List<DocumentationSet> BASE_DOCUMENTATION_SETS = buildBaseDocumentationSets();
 
     private static final List<DocumentationSet> QUICK_DOCUMENTATION_SETS = List.of(
-            new DocumentationSet(DOCSET_JAVA_24_QUICK_NAME, DOCSET_JAVA_24_QUICK_PATH),
-            new DocumentationSet(DOCSET_JAVA_25_QUICK_NAME, DOCSET_JAVA_25_QUICK_PATH),
             new DocumentationSet(DOCSET_SPRING_BOOT_QUICK_NAME, DOCSET_SPRING_BOOT_QUICK_PATH),
             new DocumentationSet(DOCSET_SPRING_FRAMEWORK_QUICK_NAME, DOCSET_SPRING_FRAMEWORK_QUICK_PATH),
             new DocumentationSet(DOCSET_SPRING_AI_QUICK_NAME, DOCSET_SPRING_AI_QUICK_PATH));
diff --git a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
index 5b6ac615..0e37992b 100644
--- a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
+++ b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
@@ -1,6 +1,7 @@
 package com.williamcallahan.javachat.cli;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
@@ -9,6 +10,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.List;
+import java.util.Set;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -16,6 +18,8 @@
  */
 class JavaApiDocumentationSourceParityTest {
 
+    private static final Set<String> LEGACY_QUICK_JAVA_DOCSET_TOKENS = Set.of("java24", "java25");
+
     @Test
     void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOException, InterruptedException {
         List<JavaApiDocumentationSource> canonicalJavaApiSources = DocsSourceRegistry.javaApiDocumentationSources();
@@ -23,11 +27,13 @@ void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOExce
                 .map(javaApiDocumentationSource -> new DocumentationSet(
                         javaApiDocumentationSource.displayName(), javaApiDocumentationSource.relativeMirrorPath()))
                 .toList();
-        List<DocumentationSet> actualCliDocumentationSets = DocumentationSetCatalog.baseSets().stream()
+        List<DocumentationSet> actualCliDocumentationSets = DocumentationSetCatalog.allSets().stream()
                 .filter(expectedCliDocumentationSets::contains)
                 .toList();
 
         assertEquals(expectedCliDocumentationSets, actualCliDocumentationSets);
+        assertFalse(DocumentationSetCatalog.allSets().stream()
+                .anyMatch(documentationSet -> documentationSet.matchesAny(LEGACY_QUICK_JAVA_DOCSET_TOKENS)));
 
         Path fetchScriptPath = Path.of("scripts", "fetch_all_docs.sh").toAbsolutePath();
         ProcessBuilder fetchSourceListingCommand =

From 1f8489efb0f4db3360ab9f45b2454bff112cb22f Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:33:33 -0700
Subject: [PATCH 22/40] test(retrieval): preserve distinct unmapped local
 sources

Prove that unresolved file URLs retain their raw identity because normalizing them to the shared redacted sentinel would collapse unrelated documents.
---
 .../service/RetrievalServiceTest.java         | 32 +++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
index 06f6fb4a..8bc0aeb0 100644
--- a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
@@ -114,6 +114,38 @@ void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations()
         assertEquals(0, citationOutcome.failedConversionCount());
     }
 
+    @Test
+    void preservesDistinctUnmappedLocalDocumentsWithoutContentHashes() {
+        HybridSearchService hybridSearchService = mock(HybridSearchService.class);
+        RerankerService rerankerService = mock(RerankerService.class);
+        DocumentFactory documentFactory = mock(DocumentFactory.class);
+        AppProperties appProperties = new AppProperties();
+        RetrievalService retrievalService =
+                new RetrievalService(hybridSearchService, appProperties, rerankerService, documentFactory);
+
+        Document firstUnmappedLocalDocument = Document.builder()
+                .id("first-unmapped-local")
+                .text("First local document")
+                .metadata("url", "file:///unmapped/first.html")
+                .build();
+        Document secondUnmappedLocalDocument = Document.builder()
+                .id("second-unmapped-local")
+                .text("Second local document")
+                .metadata("url", "file:///unmapped/second.html")
+                .build();
+        List<Document> retrievalCandidates = List.of(firstUnmappedLocalDocument, secondUnmappedLocalDocument);
+        when(hybridSearchService.searchOutcome(anyString(), anyInt(), any(RetrievalConstraint.class)))
+                .thenReturn(new HybridSearchService.SearchOutcome(retrievalCandidates, List.of()));
+        when(rerankerService.rerank(anyString(), anyList(), anyInt())).thenAnswer(rerankerInvocation -> {
+            List<Document> deduplicatedCandidates = rerankerInvocation.getArgument(1);
+            return deduplicatedCandidates;
+        });
+
+        RetrievalService.RetrievalOutcome retrievalOutcome = retrievalService.retrieveOutcome("Local documentation");
+
+        assertEquals(retrievalCandidates, retrievalOutcome.documents());
+    }
+
     @Test
     void propagatesStrictHybridSearchFailure() {
         HybridSearchService hybridSearchService = mock(HybridSearchService.class);

From 3f4d56735ffdc3409fe7aa503ba97e9c428f1b02 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 13:33:47 -0700
Subject: [PATCH 23/40] test(streaming): separate provider routing coverage

Move routing and failure-classification tests into their focused owner so the streaming service suite remains below the repository monolith threshold.
---
 .../service/OpenAIStreamingServiceTest.java   | 169 +---------------
 .../OpenAiProviderRoutingServiceTest.java     | 191 ++++++++++++++++++
 2 files changed, 194 insertions(+), 166 deletions(-)
 create mode 100644 src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java

diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
index e4afed13..31305dff 100644
--- a/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAIStreamingServiceTest.java
@@ -21,11 +21,6 @@
 import com.openai.core.http.Headers;
 import com.openai.core.http.StreamResponse;
 import com.openai.errors.InternalServerException;
-import com.openai.errors.NotFoundException;
-import com.openai.errors.OpenAIIoException;
-import com.openai.errors.PermissionDeniedException;
-import com.openai.errors.RateLimitException;
-import com.openai.errors.UnauthorizedException;
 import com.openai.models.ErrorObject;
 import com.openai.models.responses.ResponseCreateParams;
 import com.openai.models.responses.ResponseStreamEvent;
@@ -37,7 +32,6 @@
 import com.williamcallahan.javachat.application.streaming.StreamingFailureReporter;
 import com.williamcallahan.javachat.domain.prompt.StructuredPrompt;
 import com.williamcallahan.javachat.web.SseConstants;
-import java.io.InterruptedIOException;
 import java.time.Duration;
 import java.util.List;
 import java.util.Objects;
@@ -48,17 +42,14 @@
 import org.junit.jupiter.api.Test;
 import org.slf4j.LoggerFactory;
 import org.springframework.test.util.ReflectionTestUtils;
-import reactor.core.Exceptions;
 import reactor.core.publisher.Mono;
 import reactor.test.StepVerifier;
 
 /**
- * Verifies primary-provider backoff and streaming failure classification.
+ * Verifies streaming failure reporting, pre-text provider retries, and completion validation.
  *
- * <p>Backoff tests target {@link OpenAiProviderRoutingService#shouldBackoffPrimary} directly
- * (package-private, same package). Streaming recovery tests exercise the public
- * {@link OpenAIStreamingService#isRecoverableStreamingFailure} API that delegates to
- * the routing service.</p>
+ * <p>Provider routing policy is verified in {@link OpenAiProviderRoutingServiceTest} so this
+ * suite stays focused on SDK transport and stream-facing behavior.</p>
  */
 class OpenAIStreamingServiceTest {
     private final Logger serviceLogger = (Logger) LoggerFactory.getLogger(OpenAIStreamingService.class);
@@ -85,12 +76,6 @@ void stopCapturingServiceLogs() {
         streamingFailureLogEvents.list.clear();
     }
 
-    private OpenAiProviderRoutingService createRoutingService() {
-        RateLimitService rateLimitService = mock(RateLimitService.class);
-        return new OpenAiProviderRoutingService(
-                rateLimitService, 600, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
-    }
-
     private OpenAIStreamingService createStreamingService() {
         RateLimitService rateLimitService = mock(RateLimitService.class);
         OpenAiRequestFactory requestFactory =
@@ -101,112 +86,6 @@ private OpenAIStreamingService createStreamingService() {
                 rateLimitService, requestFactory, providerRoutingService, new OpenAiStreamingFailureReporter());
     }
 
-    @Test
-    void shouldBackoffPrimaryTreatsSdkIoAsBackoffEligible() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        assertTrue(routingService.shouldBackoffPrimary(new OpenAIIoException("io")));
-    }
-
-    @Test
-    void shouldBackoffPrimaryIgnoresCallerCancellationWrappedBySdkIo() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
-        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
-
-        assertFalse(routingService.shouldBackoffPrimary(cancelledCompletion));
-    }
-
-    @Test
-    void callerCancellationKeepsConfiguredPrimaryProviderEligible() {
-        RateLimitService rateLimitService = mock(RateLimitService.class);
-        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
-                .thenReturn(true);
-        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
-                .thenReturn(true);
-        OpenAiProviderRoutingService routingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
-        OpenAIClient openAiClient = mock(OpenAIClient.class);
-        OpenAIClient githubModelsClient = mock(OpenAIClient.class);
-        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
-        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
-
-        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, cancelledCompletion);
-
-        List<OpenAiProviderCandidate> availableProviders =
-                routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
-        assertEquals(2, availableProviders.size());
-        assertEquals(
-                RateLimitService.ApiProvider.OPENAI, availableProviders.get(0).provider());
-    }
-
-    @Test
-    void shouldBackoffPrimaryTreats401AsBackoffEligible() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        Headers headers = Headers.builder().build();
-        UnauthorizedException unauthorized =
-                UnauthorizedException.builder().headers(headers).build();
-        assertTrue(routingService.shouldBackoffPrimary(unauthorized));
-    }
-
-    @Test
-    void shouldBackoffPrimaryTreats429AsBackoffEligible() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        Headers headers = Headers.builder().build();
-        RateLimitException rateLimit =
-                RateLimitException.builder().headers(headers).build();
-        assertTrue(routingService.shouldBackoffPrimary(rateLimit));
-    }
-
-    @Test
-    void shouldBackoffPrimaryTreats404AsBackoffEligible() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        Headers headers = Headers.builder().build();
-        NotFoundException notFoundException =
-                NotFoundException.builder().headers(headers).build();
-        assertTrue(routingService.shouldBackoffPrimary(notFoundException));
-    }
-
-    @Test
-    void shouldBackoffPrimaryDoesNotBackoffOnGenericRuntime() {
-        OpenAiProviderRoutingService routingService = createRoutingService();
-        assertFalse(routingService.shouldBackoffPrimary(new IllegalArgumentException("no")));
-    }
-
-    @Test
-    void recoverableStreamingFailureTreatsReactorOverflowTypeAsRetryable() {
-        OpenAIStreamingService streamingService = createStreamingService();
-        assertTrue(streamingService.isRecoverableStreamingFailure(Exceptions.failWithOverflow()));
-    }
-
-    @Test
-    void recoverableStreamingFailureTreatsValidationErrorsAsNonRetryable() {
-        OpenAIStreamingService streamingService = createStreamingService();
-        assertFalse(
-                streamingService.isRecoverableStreamingFailure(new IllegalArgumentException("bad request payload")));
-    }
-
-    @Test
-    void recoverableStreamingFailureTreatsNotFoundAsNonRetryable() {
-        OpenAIStreamingService streamingService = createStreamingService();
-        Headers headers = Headers.builder().build();
-        NotFoundException notFoundException =
-                NotFoundException.builder().headers(headers).build();
-        assertFalse(streamingService.isRecoverableStreamingFailure(notFoundException));
-    }
-
-    @Test
-    void recoverableStreamingFailureRejectsAuthenticationAuthorizationAndRateLimitFailures() {
-        OpenAIStreamingService streamingService = createStreamingService();
-        Headers headers = Headers.builder().build();
-
-        assertFalse(streamingService.isRecoverableStreamingFailure(
-                UnauthorizedException.builder().headers(headers).build()));
-        assertFalse(streamingService.isRecoverableStreamingFailure(
-                PermissionDeniedException.builder().headers(headers).build()));
-        assertFalse(streamingService.isRecoverableStreamingFailure(
-                RateLimitException.builder().headers(headers).build()));
-    }
-
     @Test
     void recoverableStreamingFailureUnwrapsNestedTerminalContext() {
         OpenAIStreamingService streamingService = createStreamingService();
@@ -424,48 +303,6 @@ void nonEmptyTextDeltaDisablesPreTextRetry() {
         verify(visibleTextDelta).delta();
     }
 
-    @Test
-    void primaryBackoffDoesNotHideOnlyConfiguredProvider() {
-        RateLimitService rateLimitService = mock(RateLimitService.class);
-        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
-                .thenReturn(true);
-        OpenAiProviderRoutingService routingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
-        OpenAIClient openAiClient = mock(OpenAIClient.class);
-
-        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
-
-        List<OpenAiProviderCandidate> availableProviders =
-                routingService.selectAvailableProviderCandidates(null, openAiClient);
-
-        assertEquals(1, availableProviders.size());
-        assertEquals(
-                RateLimitService.ApiProvider.OPENAI, availableProviders.get(0).provider());
-    }
-
-    @Test
-    void primaryBackoffUsesConfiguredAlternateProviderWhenAvailable() {
-        RateLimitService rateLimitService = mock(RateLimitService.class);
-        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
-                .thenReturn(true);
-        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
-                .thenReturn(true);
-        OpenAiProviderRoutingService routingService =
-                new OpenAiProviderRoutingService(rateLimitService, 600, RateLimitService.ApiProvider.OPENAI.getName());
-        OpenAIClient openAiClient = mock(OpenAIClient.class);
-        OpenAIClient githubModelsClient = mock(OpenAIClient.class);
-
-        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
-
-        List<OpenAiProviderCandidate> availableProviders =
-                routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
-
-        assertEquals(1, availableProviders.size());
-        assertEquals(
-                RateLimitService.ApiProvider.GITHUB_MODELS,
-                availableProviders.get(0).provider());
-    }
-
     @Test
     void unavailableStreamDefersErrorSeverityToRequestBoundary() {
         OpenAIStreamingService streamingService = createStreamingService();
diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java
new file mode 100644
index 00000000..a73b6a28
--- /dev/null
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java
@@ -0,0 +1,191 @@
+package com.williamcallahan.javachat.service;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+import com.openai.client.OpenAIClient;
+import com.openai.core.http.Headers;
+import com.openai.errors.NotFoundException;
+import com.openai.errors.OpenAIIoException;
+import com.openai.errors.PermissionDeniedException;
+import com.openai.errors.RateLimitException;
+import com.openai.errors.UnauthorizedException;
+import java.io.InterruptedIOException;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import reactor.core.Exceptions;
+
+/**
+ * Verifies provider ordering, primary backoff, and failure classification policy.
+ *
+ * <p>This suite targets routing directly so streaming transport tests remain focused on stream behavior.</p>
+ */
+class OpenAiProviderRoutingServiceTest {
+    private static final long PRIMARY_BACKOFF_SECONDS = 600L;
+
+    private OpenAiProviderRoutingService createRoutingService() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        return new OpenAiProviderRoutingService(
+                rateLimitService, PRIMARY_BACKOFF_SECONDS, RateLimitService.ApiProvider.GITHUB_MODELS.getName());
+    }
+
+    @Test
+    void shouldBackoffPrimaryTreatsSdkIoAsBackoffEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertTrue(routingService.shouldBackoffPrimary(new OpenAIIoException("io")));
+    }
+
+    @Test
+    void shouldBackoffPrimaryIgnoresCallerCancellationWrappedBySdkIo() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
+        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
+
+        assertFalse(routingService.shouldBackoffPrimary(cancelledCompletion));
+    }
+
+    @Test
+    void callerCancellationKeepsConfiguredPrimaryProviderEligible() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
+                .thenReturn(true);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
+                .thenReturn(true);
+        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(
+                rateLimitService, PRIMARY_BACKOFF_SECONDS, RateLimitService.ApiProvider.OPENAI.getName());
+        OpenAIClient openAiClient = mock(OpenAIClient.class);
+        OpenAIClient githubModelsClient = mock(OpenAIClient.class);
+        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
+        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
+
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, cancelledCompletion);
+
+        List<OpenAiProviderCandidate> availableProviders =
+                routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
+        assertEquals(
+                List.of(RateLimitService.ApiProvider.OPENAI, RateLimitService.ApiProvider.GITHUB_MODELS),
+                availableProviders.stream()
+                        .map(OpenAiProviderCandidate::provider)
+                        .toList());
+    }
+
+    @Test
+    void shouldBackoffPrimaryTreats401AsBackoffEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        Headers headers = Headers.builder().build();
+        UnauthorizedException unauthorized =
+                UnauthorizedException.builder().headers(headers).build();
+
+        assertTrue(routingService.shouldBackoffPrimary(unauthorized));
+    }
+
+    @Test
+    void shouldBackoffPrimaryTreats429AsBackoffEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        Headers headers = Headers.builder().build();
+        RateLimitException rateLimit =
+                RateLimitException.builder().headers(headers).build();
+
+        assertTrue(routingService.shouldBackoffPrimary(rateLimit));
+    }
+
+    @Test
+    void shouldBackoffPrimaryTreats404AsBackoffEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        Headers headers = Headers.builder().build();
+        NotFoundException notFoundException =
+                NotFoundException.builder().headers(headers).build();
+
+        assertTrue(routingService.shouldBackoffPrimary(notFoundException));
+    }
+
+    @Test
+    void shouldBackoffPrimaryDoesNotBackoffOnGenericRuntime() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertFalse(routingService.shouldBackoffPrimary(new IllegalArgumentException("no")));
+    }
+
+    @Test
+    void recoverableStreamingFailureTreatsReactorOverflowTypeAsRetryable() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertTrue(routingService.isRecoverableStreamingFailure(Exceptions.failWithOverflow()));
+    }
+
+    @Test
+    void recoverableStreamingFailureTreatsValidationErrorsAsNonRetryable() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertFalse(routingService.isRecoverableStreamingFailure(new IllegalArgumentException("bad request payload")));
+    }
+
+    @Test
+    void recoverableStreamingFailureTreatsNotFoundAsNonRetryable() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        Headers headers = Headers.builder().build();
+        NotFoundException notFoundException =
+                NotFoundException.builder().headers(headers).build();
+
+        assertFalse(routingService.isRecoverableStreamingFailure(notFoundException));
+    }
+
+    @Test
+    void recoverableStreamingFailureRejectsAuthenticationAuthorizationAndRateLimitFailures() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+        Headers headers = Headers.builder().build();
+
+        assertFalse(routingService.isRecoverableStreamingFailure(
+                UnauthorizedException.builder().headers(headers).build()));
+        assertFalse(routingService.isRecoverableStreamingFailure(
+                PermissionDeniedException.builder().headers(headers).build()));
+        assertFalse(routingService.isRecoverableStreamingFailure(
+                RateLimitException.builder().headers(headers).build()));
+    }
+
+    @Test
+    void primaryBackoffDoesNotHideOnlyConfiguredProvider() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
+                .thenReturn(true);
+        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(
+                rateLimitService, PRIMARY_BACKOFF_SECONDS, RateLimitService.ApiProvider.OPENAI.getName());
+        OpenAIClient openAiClient = mock(OpenAIClient.class);
+
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
+
+        List<OpenAiProviderCandidate> availableProviders =
+                routingService.selectAvailableProviderCandidates(null, openAiClient);
+
+        assertEquals(1, availableProviders.size());
+        assertEquals(
+                RateLimitService.ApiProvider.OPENAI, availableProviders.get(0).provider());
+    }
+
+    @Test
+    void primaryBackoffUsesConfiguredAlternateProviderWhenAvailable() {
+        RateLimitService rateLimitService = mock(RateLimitService.class);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.OPENAI))
+                .thenReturn(true);
+        when(rateLimitService.isProviderAvailable(RateLimitService.ApiProvider.GITHUB_MODELS))
+                .thenReturn(true);
+        OpenAiProviderRoutingService routingService = new OpenAiProviderRoutingService(
+                rateLimitService, PRIMARY_BACKOFF_SECONDS, RateLimitService.ApiProvider.OPENAI.getName());
+        OpenAIClient openAiClient = mock(OpenAIClient.class);
+        OpenAIClient githubModelsClient = mock(OpenAIClient.class);
+
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, new OpenAIIoException("io"));
+
+        List<OpenAiProviderCandidate> availableProviders =
+                routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
+
+        assertEquals(1, availableProviders.size());
+        assertEquals(
+                RateLimitService.ApiProvider.GITHUB_MODELS,
+                availableProviders.get(0).provider());
+    }
+}

From ce3a9efa585f9b5ace5a6a1eb8f0d4a278f72841 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:38:56 -0700
Subject: [PATCH 24/40] fix(config): validate Java API manifest locations

---
 .../config/JavaApiDocumentationManifest.java  | 72 ++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
index 563a6b7b..76a4a577 100644
--- a/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
+++ b/src/main/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifest.java
@@ -5,7 +5,11 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.InputStreamReader;
+import java.net.URI;
+import java.net.URISyntaxException;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.InvalidPathException;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashSet;
@@ -25,7 +29,14 @@ final class JavaApiDocumentationManifest {
     private static final String MANIFEST_RESOURCE = "/java-api-documentation-sources.manifest";
     private static final String MANIFEST_DELIMITER = "|";
     private static final String MANIFEST_DELIMITER_REGEX = "\\|";
+    private static final String MIRROR_PATH_CURRENT_SEGMENT = ".";
+    private static final String MIRROR_PATH_PARENT_SEGMENT = "..";
+    private static final String MIRROR_PATH_SEGMENT_SEPARATOR = "/";
+    private static final String REMOTE_BASE_URL_HTTPS_SCHEME = "https";
     private static final int MINIMUM_MANIFEST_LINE_COUNT = 2;
+    private static final int MANIFEST_ASCII_CONTROL_MAXIMUM = 0x1F;
+    private static final int MANIFEST_ASCII_DELETE_CHARACTER = 0x7F;
+    private static final char MIRROR_PATH_BACKSLASH = '\\';
     private static final Pattern CANONICAL_UNSIGNED_INTEGER = Pattern.compile("(?:0|[1-9][0-9]*)");
 
     private JavaApiDocumentationManifest() {}
@@ -98,11 +109,61 @@ static void requireManifestText(String manifestText, String fieldName, boolean a
         if (!allowEmpty && manifestText.isEmpty()) {
             throw new IllegalArgumentException(fieldName + " cannot be blank");
         }
-        if (!allowEmpty && hasBoundaryWhitespace(manifestText)) {
+        if (hasAsciiControlCharacter(manifestText)) {
+            throw new IllegalArgumentException(fieldName + " cannot contain control characters");
+        }
+        if (hasBoundaryWhitespace(manifestText)) {
             throw new IllegalArgumentException(fieldName + " cannot have boundary whitespace");
         }
     }
 
+    static void requireHttpsRemoteBaseUrl(String remoteBaseUrl) {
+        requireManifestText(remoteBaseUrl, "remoteBaseUrl", false);
+        if (!remoteBaseUrl.endsWith(MIRROR_PATH_SEGMENT_SEPARATOR)) {
+            throw new IllegalArgumentException("remoteBaseUrl must have a trailing slash");
+        }
+        try {
+            URI remoteBaseUri = new URI(remoteBaseUrl).parseServerAuthority();
+            if (!remoteBaseUri.isAbsolute()
+                    || !REMOTE_BASE_URL_HTTPS_SCHEME.equals(remoteBaseUri.getScheme())
+                    || remoteBaseUri.getRawAuthority() == null
+                    || remoteBaseUri.getRawAuthority().isEmpty()
+                    || remoteBaseUri.getHost() == null) {
+                throw new IllegalArgumentException("remoteBaseUrl must be an absolute HTTPS URL with authority");
+            }
+        } catch (URISyntaxException invalidRemoteBaseUrl) {
+            throw new IllegalArgumentException(
+                    "remoteBaseUrl must be an absolute HTTPS URL with authority", invalidRemoteBaseUrl);
+        }
+    }
+
+    static void requireNormalizedRelativeMirrorPath(String relativeMirrorPath) {
+        requireManifestText(relativeMirrorPath, "relativeMirrorPath", false);
+        if (relativeMirrorPath.indexOf(MIRROR_PATH_BACKSLASH) >= 0) {
+            throw new IllegalArgumentException("relativeMirrorPath cannot contain backslashes");
+        }
+
+        Path mirrorPath;
+        try {
+            mirrorPath = Path.of(relativeMirrorPath);
+        } catch (InvalidPathException invalidRelativeMirrorPath) {
+            throw new IllegalArgumentException("relativeMirrorPath must be a valid path", invalidRelativeMirrorPath);
+        }
+        if (mirrorPath.isAbsolute()) {
+            throw new IllegalArgumentException("relativeMirrorPath must be relative");
+        }
+        if (!mirrorPath.equals(mirrorPath.normalize())) {
+            throw new IllegalArgumentException("relativeMirrorPath must be normalized");
+        }
+        for (String mirrorPathSegment : relativeMirrorPath.split(MIRROR_PATH_SEGMENT_SEPARATOR, -1)) {
+            if (mirrorPathSegment.isEmpty()
+                    || MIRROR_PATH_CURRENT_SEGMENT.equals(mirrorPathSegment)
+                    || MIRROR_PATH_PARENT_SEGMENT.equals(mirrorPathSegment)) {
+                throw new IllegalArgumentException("relativeMirrorPath contains an invalid segment");
+            }
+        }
+    }
+
     static String serialize(JavaApiDocumentationSource source) {
         return String.join(
                 MANIFEST_DELIMITER,
@@ -179,6 +240,15 @@ private static boolean isAsciiWhitespace(char manifestCharacter) {
                 || manifestCharacter == 0x0B;
     }
 
+    private static boolean hasAsciiControlCharacter(String manifestText) {
+        return manifestText.chars().anyMatch(JavaApiDocumentationManifest::isAsciiControlCharacter);
+    }
+
+    private static boolean isAsciiControlCharacter(int characterCodePoint) {
+        return characterCodePoint <= MANIFEST_ASCII_CONTROL_MAXIMUM
+                || characterCodePoint == MANIFEST_ASCII_DELETE_CHARACTER;
+    }
+
     private static IllegalStateException invalidLine(int manifestLineNumber, String problem) {
         return new IllegalStateException(
                 "Canonical Java API documentation source manifest line " + manifestLineNumber + " " + problem);

From 45a9a0fd1e7ebc4021826ea74723aabbc2078e2f Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:38:58 -0700
Subject: [PATCH 25/40] fix(config): protect Java API source projections

---
 .../javachat/config/DocsSourceRegistry.java               | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java b/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
index 557d9ad2..39b4819d 100644
--- a/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
+++ b/src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
@@ -117,7 +117,7 @@ private DocsSourceRegistry() {}
      * Describes one complete Java API mirror projected from the canonical manifest.
      *
      * @param javaRelease Java release number used by retrieval provenance
-     * @param remoteBaseUrl authoritative Oracle Javadoc base URL
+     * @param remoteBaseUrl authoritative Javadoc base URL
      * @param relativeMirrorPath canonical path beneath {@code data/docs}
      * @param displayName operator-facing ingestion name
      * @param cutDirectories number of leading remote path segments removed during mirroring
@@ -140,8 +140,8 @@ public record JavaApiDocumentationSource(
             if (parsedJavaRelease < 1) {
                 throw new IllegalArgumentException("Java release must be positive");
             }
-            JavaApiDocumentationManifest.requireManifestText(remoteBaseUrl, "remoteBaseUrl", false);
-            JavaApiDocumentationManifest.requireManifestText(relativeMirrorPath, "relativeMirrorPath", false);
+            JavaApiDocumentationManifest.requireHttpsRemoteBaseUrl(remoteBaseUrl);
+            JavaApiDocumentationManifest.requireNormalizedRelativeMirrorPath(relativeMirrorPath);
             JavaApiDocumentationManifest.requireManifestText(displayName, "displayName", false);
             if (cutDirectories < 0) {
                 throw new IllegalArgumentException("Java API cut directories cannot be negative");
@@ -168,7 +168,7 @@ public String toManifestRow() {
      * @return immutable sources in manifest order
      */
     public static List<JavaApiDocumentationSource> javaApiDocumentationSources() {
-        return JAVA_API_DOCUMENTATION_SOURCES;
+        return List.copyOf(JAVA_API_DOCUMENTATION_SOURCES);
     }
 
     private static Properties loadDocsSourceProperties() {

From 7b81b34fc3d342e80642784b7932b4c91dc459cd Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:00 -0700
Subject: [PATCH 26/40] fix(ingestion): enforce canonical Java API selectors

---
 .../javachat/cli/DocumentationSet.java        | 41 ++++++++++++++-----
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSet.java b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSet.java
index b16ba010..c5a5978d 100644
--- a/src/main/java/com/williamcallahan/javachat/cli/DocumentationSet.java
+++ b/src/main/java/com/williamcallahan/javachat/cli/DocumentationSet.java
@@ -1,42 +1,63 @@
 package com.williamcallahan.javachat.cli;
 
+import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import java.util.Locale;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * Identifies a documentation set processed by the CLI ingestion pipeline.
  *
  * <p>The relative path is resolved under the configured docs root (for example, {@code data/docs}).
- * The ID is a stable token used for filtering in {@code DOCS_SETS}.</p>
+ * Manifest-backed Java API sets accept only their canonical relative mirror path; other sets retain
+ * their established filter tokens.</p>
  *
  * @param displayName user-facing name for logs
  * @param relativePath relative path under the docs root
  */
 record DocumentationSet(String displayName, String relativePath) {
 
-    String docSetId() {
+    private static final Set<String> JAVA_API_RELATIVE_MIRROR_PATHS =
+            DocsSourceRegistry.javaApiDocumentationSources().stream()
+                    .map(javaApiDocumentationSource -> javaApiDocumentationSource.relativeMirrorPath())
+                    .collect(Collectors.toUnmodifiableSet());
+
+    String primarySelector() {
+        if (isManifestBackedJavaApiSet()) {
+            return relativePath;
+        }
         return normalizeToken(relativePath.replace('/', '-'));
     }
 
-    boolean matchesAny(final Set<String> tokens) {
-        if (tokens == null || tokens.isEmpty()) {
+    boolean matchesSelectorTokens(final Set<String> selectorTokens) {
+        if (selectorTokens == null || selectorTokens.isEmpty()) {
             return false;
         }
+        if (isManifestBackedJavaApiSet()) {
+            return selectorTokens.contains(relativePath);
+        }
         final String normalizedName = normalizeToken(displayName);
         final String normalizedPath = normalizeToken(relativePath);
-        final String normalizedId = docSetId();
-        for (String token : tokens) {
-            if (token.equals(normalizedId) || token.equals(normalizedName) || token.equals(normalizedPath)) {
+        final String normalizedId = primarySelector();
+        for (String selectorToken : selectorTokens) {
+            final String normalizedSelectorToken = normalizeToken(selectorToken);
+            if (normalizedSelectorToken.equals(normalizedId)
+                    || normalizedSelectorToken.equals(normalizedName)
+                    || normalizedSelectorToken.equals(normalizedPath)) {
                 return true;
             }
         }
         return false;
     }
 
-    private static String normalizeToken(final String token) {
-        if (token == null) {
+    private boolean isManifestBackedJavaApiSet() {
+        return JAVA_API_RELATIVE_MIRROR_PATHS.contains(relativePath);
+    }
+
+    private static String normalizeToken(final String selectorToken) {
+        if (selectorToken == null) {
             return "";
         }
-        return token.trim().toLowerCase(Locale.ROOT);
+        return selectorToken.trim().toLowerCase(Locale.ROOT);
     }
 }

From 3259bfa7e9f9c8d7d566cfdb793e53f251d697f1 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:01 -0700
Subject: [PATCH 27/40] fix(ingestion): preserve canonical selector case

---
 .../javachat/cli/DocumentProcessor.java       | 49 +++++++++----------
 1 file changed, 23 insertions(+), 26 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/cli/DocumentProcessor.java b/src/main/java/com/williamcallahan/javachat/cli/DocumentProcessor.java
index 0c71165b..f1fef7a3 100644
--- a/src/main/java/com/williamcallahan/javachat/cli/DocumentProcessor.java
+++ b/src/main/java/com/williamcallahan/javachat/cli/DocumentProcessor.java
@@ -69,6 +69,9 @@ public class DocumentProcessor {
     private static final String LOG_DOCSET_FILTER = "Doc set filter active";
     private static final String LOG_DOCSET_SELECTED = "Doc sets selected: {} set(s)";
 
+    private static final String DOCSET_ALL_SELECTOR = "all";
+    private static final String DOCSET_FILTER_DELIMITER = ",";
+
     private static final String SKIP_REASON_INVALID_PATH = "invalid path";
     private static final String SKIP_REASON_DIR_MISSING = "directory not found";
     private static final String SKIP_REASON_NO_ELIGIBLE_FILES = "no eligible files";
@@ -248,17 +251,17 @@ private List<DocumentationSet> selectDocumentationSets(final EnvironmentConfig c
             }
             return DocumentationSetCatalog.baseSets();
         }
-        final Set<String> tokens = parseDocSetFilter(filter);
-        if (tokens.isEmpty() || tokens.contains("all")) {
+        final Set<String> selectorTokens = parseDocSetFilter(filter);
+        if (selectorTokens.isEmpty() || selectorTokens.stream().anyMatch(DOCSET_ALL_SELECTOR::equalsIgnoreCase)) {
             return DocumentationSetCatalog.allSets();
         }
-        final List<DocumentationSet> selectedSets = new ArrayList<>();
-        for (DocumentationSet docSet : DocumentationSetCatalog.allSets()) {
-            if (docSet.matchesAny(tokens)) {
-                selectedSets.add(docSet);
+        final List<DocumentationSet> selectedDocumentationSets = new ArrayList<>();
+        for (DocumentationSet documentationSet : DocumentationSetCatalog.allSets()) {
+            if (documentationSet.matchesSelectorTokens(selectorTokens)) {
+                selectedDocumentationSets.add(documentationSet);
             }
         }
-        if (selectedSets.isEmpty()) {
+        if (selectedDocumentationSets.isEmpty()) {
             throw new DocumentProcessingException(String.format(
                     Locale.ROOT,
                     "DOCS_SETS matched no documentation sets. Available doc sets: %s",
@@ -266,38 +269,32 @@ private List<DocumentationSet> selectDocumentationSets(final EnvironmentConfig c
         }
         if (LOGGER.isInfoEnabled()) {
             LOGGER.info(LOG_DOCSET_FILTER);
-            LOGGER.info(LOG_DOCSET_SELECTED, selectedSets.size());
+            LOGGER.info(LOG_DOCSET_SELECTED, selectedDocumentationSets.size());
         }
-        return selectedSets;
+        return selectedDocumentationSets;
     }
 
     private static Set<String> parseDocSetFilter(final String filter) {
-        final Set<String> tokens = new LinkedHashSet<>();
+        final Set<String> selectorTokens = new LinkedHashSet<>();
         if (filter == null || filter.isBlank()) {
-            return tokens;
+            return selectorTokens;
         }
-        for (String token : filter.split(",")) {
-            final String normalized = normalizeToken(token);
-            if (!normalized.isBlank()) {
-                tokens.add(normalized);
+        for (String commaSeparatedSelector : filter.split(DOCSET_FILTER_DELIMITER)) {
+            final String selectorToken = commaSeparatedSelector.trim();
+            if (!selectorToken.isBlank()) {
+                selectorTokens.add(selectorToken);
             }
         }
-        return tokens;
+        return selectorTokens;
     }
 
-    private static String formatDocSetSummary(final List<DocumentationSet> docSets) {
-        return docSets.stream()
-                .map(docSet -> docSet.docSetId() + " (" + docSet.displayName() + ")")
+    private static String formatDocSetSummary(final List<DocumentationSet> documentationSets) {
+        return documentationSets.stream()
+                .map(documentationSet ->
+                        documentationSet.primarySelector() + " (" + documentationSet.displayName() + ")")
                 .collect(Collectors.joining(", "));
     }
 
-    private static String normalizeToken(final String token) {
-        if (token == null) {
-            return "";
-        }
-        return token.trim().toLowerCase(Locale.ROOT);
-    }
-
     private void logProcessingStats(final int processed, final long elapsedMillis) {
         if (!LOGGER.isInfoEnabled()) {
             return;

From 5fe43c547c6b70898cf6eceff64ab4ec16383d56 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:02 -0700
Subject: [PATCH 28/40] fix(provider): classify OkHttp call timeouts

---
 .../service/OpenAiProviderRoutingService.java  | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
index e94e3651..330bee89 100644
--- a/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingService.java
@@ -37,6 +37,14 @@ public class OpenAiProviderRoutingService {
     private static final String PROVIDER_SETTING_GITHUB_MODELS_ALT = "github-models";
     private static final String PROVIDER_SETTING_GITHUB = "github";
 
+    /**
+     * Identifies the whole-call timeout message emitted by OkHttp 4.12 {@code RealCall.timeoutExit}.
+     *
+     * <p>OpenAI Java 4.16 wraps the corresponding {@link InterruptedIOException} in an
+     * {@link OpenAIIoException}, which is a provider failure rather than caller cancellation.</p>
+     */
+    private static final String OK_HTTP_CALL_TIMEOUT_MESSAGE = "timeout";
+
     private static final int HTTP_REQUEST_TIMEOUT = 408;
     private static final int HTTP_CONFLICT = 409;
     private static final int HTTP_TOO_MANY_REQUESTS = 429;
@@ -306,8 +314,9 @@ private boolean isCallerCancellation(Throwable throwable) {
                 Thread.currentThread().interrupt();
                 return true;
             }
-            if (cancellationCandidate instanceof InterruptedIOException
-                    && !(cancellationCandidate instanceof SocketTimeoutException)) {
+            if (cancellationCandidate instanceof InterruptedIOException interruptedIoException
+                    && !(interruptedIoException instanceof SocketTimeoutException)
+                    && !isOkHttpCallTimeout(interruptedIoException)) {
                 return true;
             }
             String cancellationMessage = cancellationCandidate.getMessage();
@@ -320,6 +329,11 @@ private boolean isCallerCancellation(Throwable throwable) {
         return false;
     }
 
+    private static boolean isOkHttpCallTimeout(InterruptedIOException interruptedIoException) {
+        return interruptedIoException.getClass().equals(InterruptedIOException.class)
+                && OK_HTTP_CALL_TIMEOUT_MESSAGE.equals(interruptedIoException.getMessage());
+    }
+
     private boolean isPrimaryInBackoff() {
         return System.currentTimeMillis() < primaryBackoffUntilEpochMs;
     }

From 2a84071261c8d0bdf2c1d9293114b6ca9a6fcce7 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:04 -0700
Subject: [PATCH 29/40] fix(retrieval): retain distinct redacted citations

---
 .../javachat/service/RetrievalService.java    | 28 ++++++++++++++-----
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java b/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
index f1e967f1..34e7ae73 100644
--- a/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
+++ b/src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
@@ -36,6 +36,7 @@ public class RetrievalService {
     private static final String METADATA_TITLE = "title";
     private static final String METADATA_PACKAGE = "package";
     private static final String METADATA_HASH = "hash";
+    private static final String FILE_URL_PREFIX = "file://";
     private static final char URL_FRAGMENT_DELIMITER = '#';
 
     private final HybridSearchService hybridSearchService;
@@ -202,8 +203,8 @@ private List<Document> deduplicateByContentHashThenHashlessCanonicalUrl(List<Doc
                 String documentUrl = stringMetadataValue(document.getMetadata(), METADATA_URL)
                         .trim();
                 if (!documentUrl.isBlank()) {
-                    String canonicalDocumentUrl = documentUrl.startsWith("file://")
-                            ? DocsSourceRegistry.resolveLocalPath(documentUrl.substring("file://".length()))
+                    String canonicalDocumentUrl = documentUrl.startsWith(FILE_URL_PREFIX)
+                            ? DocsSourceRegistry.resolveLocalPath(documentUrl.substring(FILE_URL_PREFIX.length()))
                                     .map(DocsSourceRegistry::canonicalizeHttpDocUrl)
                                     .orElse(documentUrl)
                             : DocsSourceRegistry.normalizeDocUrl(documentUrl);
@@ -282,7 +283,7 @@ public CitationOutcome toCitations(List<Document> documents) {
             return new CitationOutcome(List.of(), 0);
         }
         List<Citation> citations = new ArrayList<>();
-        Set<String> retainedCitationUrls = new HashSet<>();
+        Set<String> retainedCitationIdentities = new HashSet<>();
         int failedConversionCount = 0;
         for (Document sourceDocument : documents) {
             if (sourceDocument == null) {
@@ -294,9 +295,8 @@ public CitationOutcome toCitations(List<Document> documents) {
                 String title = stringMetadataValue(sourceDocMetadata, METADATA_TITLE);
                 String packageName = stringMetadataValue(sourceDocMetadata, METADATA_PACKAGE);
                 String url = refineCitationUrl(rawUrl, sourceDocument.getText(), packageName);
-                String fragmentlessCitationSourceUrl = fragmentlessCitationSourceUrl(url);
-                if (!fragmentlessCitationSourceUrl.isBlank()
-                        && !retainedCitationUrls.add(fragmentlessCitationSourceUrl)) {
+                String citationIdentity = citationIdentityFor(rawUrl, url);
+                if (!citationIdentity.isBlank() && !retainedCitationIdentities.add(citationIdentity)) {
                     continue;
                 }
                 citations.add(new Citation(url, title, "", trimmedCitationSnippet(sourceDocument.getText())));
@@ -324,6 +324,19 @@ private static String fragmentlessCitationSourceUrl(String citationUrl) {
         return fragmentDelimiterIndex < 0 ? citationUrl : citationUrl.substring(0, fragmentDelimiterIndex);
     }
 
+    /**
+     * Keeps redacted display URLs from merging citations for separate unresolved local sources.
+     */
+    private static String citationIdentityFor(String rawUrl, String citationUrl) {
+        String trimmedRawUrl = rawUrl.trim();
+        if (trimmedRawUrl.startsWith(FILE_URL_PREFIX)
+                && DocsSourceRegistry.resolveLocalPath(trimmedRawUrl.substring(FILE_URL_PREFIX.length()))
+                        .isEmpty()) {
+            return fragmentlessCitationSourceUrl(trimmedRawUrl);
+        }
+        return fragmentlessCitationSourceUrl(citationUrl);
+    }
+
     /**
      * Refines a raw document URL through nested-type and member-anchor resolution, then canonicalizes.
      *
@@ -357,7 +370,8 @@ private String safeMetadataValueForLogging(Map<String, ?> metadata, String key)
             return "";
         }
         try {
-            return String.valueOf(metadataValue);
+            String metadataText = String.valueOf(metadataValue);
+            return METADATA_URL.equals(key) ? DocsSourceRegistry.normalizeDocUrl(metadataText) : metadataText;
         } catch (RuntimeException _) {
             return "[unprintable:" + metadataValue.getClass().getSimpleName() + "]";
         }

From 26318494e44b227adb702321efac51b547b6e943 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:05 -0700
Subject: [PATCH 30/40] fix(docs): validate canonical Java API source rows

---
 scripts/lib/documentation_sources.sh | 90 +++++++++++++++++++++++-----
 1 file changed, 75 insertions(+), 15 deletions(-)

diff --git a/scripts/lib/documentation_sources.sh b/scripts/lib/documentation_sources.sh
index 9d4f8966..34503c7c 100644
--- a/scripts/lib/documentation_sources.sh
+++ b/scripts/lib/documentation_sources.sh
@@ -24,6 +24,60 @@ has_boundary_whitespace() {
     [[ "$manifest_text" =~ ^[[:space:]] || "$manifest_text" =~ [[:space:]]$ ]]
 }
 
+has_manifest_control_character() {
+    local manifest_text="$1"
+    local LC_ALL=C
+    [[ "$manifest_text" == *[[:cntrl:]]* ]]
+}
+
+is_absolute_https_remote_base_url() {
+    local remote_base_url="$1"
+    if [[ "$remote_base_url" != https://* || "$remote_base_url" != */ ]]; then
+        return 1
+    fi
+    if [[ "$remote_base_url" == *[[:space:]]* || "$remote_base_url" == *\\* ]]; then
+        return 1
+    fi
+
+    local remote_authority_and_path="${remote_base_url#https://}"
+    local remote_authority="${remote_authority_and_path%%[/?#]*}"
+    if [ -z "$remote_authority" ]; then
+        return 1
+    fi
+
+    local remote_host_and_port="${remote_authority##*@}"
+    if [ -z "$remote_host_and_port" ]; then
+        return 1
+    fi
+    if [[ "$remote_host_and_port" == \[* ]]; then
+        [[ "$remote_host_and_port" =~ ^\[[0-9A-Fa-f:.]+\](:[0-9]+)?$ ]]
+        return
+    fi
+    [[ "$remote_host_and_port" =~ ^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$ ]]
+}
+
+is_normalized_relative_mirror_path() {
+    local relative_mirror_path="$1"
+    if [[ "$relative_mirror_path" == /* \
+        || "$relative_mirror_path" == */ \
+        || "$relative_mirror_path" == *//* \
+        || "$relative_mirror_path" == *\\* ]]; then
+        return 1
+    fi
+
+    local IFS='/'
+    local -a mirror_path_segments
+    read -r -a mirror_path_segments <<< "$relative_mirror_path"
+    local mirror_path_segment
+    for mirror_path_segment in "${mirror_path_segments[@]}"; do
+        if [ -z "$mirror_path_segment" ] \
+            || [ "$mirror_path_segment" = "." ] \
+            || [ "$mirror_path_segment" = ".." ]; then
+            return 1
+        fi
+    done
+}
+
 is_blank_manifest_line() {
     local manifest_line="$1"
     local LC_ALL=C
@@ -110,13 +164,29 @@ load_java_api_documentation_sources() {
             echo "Java API source manifest line $manifest_line_number has an invalid Java release" >&2
             return 1
         fi
-        if [ -z "$remoteBaseUrl" ] || [ -z "$relativeMirrorPath" ] || [ -z "$displayName" ] \
-            || has_boundary_whitespace "$remoteBaseUrl" \
-            || has_boundary_whitespace "$relativeMirrorPath" \
-            || has_boundary_whitespace "$displayName"; then
+        if [ -z "$remoteBaseUrl" ] || [ -z "$relativeMirrorPath" ] || [ -z "$displayName" ]; then
             echo "Java API source manifest line $manifest_line_number has a blank required field" >&2
             return 1
         fi
+        if has_boundary_whitespace "$remoteBaseUrl" \
+            || has_boundary_whitespace "$relativeMirrorPath" \
+            || has_boundary_whitespace "$displayName" \
+            || has_boundary_whitespace "$rejectRegex" \
+            || has_manifest_control_character "$remoteBaseUrl" \
+            || has_manifest_control_character "$relativeMirrorPath" \
+            || has_manifest_control_character "$displayName" \
+            || has_manifest_control_character "$rejectRegex"; then
+            echo "Java API source manifest line $manifest_line_number has invalid text fields" >&2
+            return 1
+        fi
+        if ! is_absolute_https_remote_base_url "$remoteBaseUrl"; then
+            echo "Java API source manifest line $manifest_line_number has an invalid remote base URL" >&2
+            return 1
+        fi
+        if ! is_normalized_relative_mirror_path "$relativeMirrorPath"; then
+            echo "Java API source manifest line $manifest_line_number has an invalid relative mirror path" >&2
+            return 1
+        fi
         if ! is_canonical_manifest_integer "$cutDirectories"; then
             echo "Java API source manifest line $manifest_line_number has invalid cut directories" >&2
             return 1
@@ -160,19 +230,9 @@ load_java_api_documentation_sources() {
 }
 
 append_java_api_fetch_sources() {
-    local docs_root="$1"
     local java_api_source_projection
     for java_api_source_projection in "${JAVA_API_SOURCE_PROJECTIONS[@]}"; do
-        local javaRelease
-        local remoteBaseUrl
-        local relativeMirrorPath
-        local displayName
-        local cutDirectories
-        local minimumHtmlFiles
-        local rejectRegex
-        local allowPartial
-        IFS='|' read -r javaRelease remoteBaseUrl relativeMirrorPath displayName cutDirectories minimumHtmlFiles rejectRegex allowPartial <<< "$java_api_source_projection"
-        DOC_SOURCES+=("$remoteBaseUrl|$docs_root/$relativeMirrorPath|$displayName|$cutDirectories|$minimumHtmlFiles|$rejectRegex|$allowPartial")
+        DOC_SOURCES+=("$java_api_source_projection")
     done
 }
 

From 2a120a5ce927bc655f9ca3f197fa44af6324f3e8 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:05 -0700
Subject: [PATCH 31/40] fix(docs): dispatch exact Java API source rows

---
 scripts/fetch_all_docs.sh | 145 +++++++++++++++++++++++++-------------
 1 file changed, 96 insertions(+), 49 deletions(-)

diff --git a/scripts/fetch_all_docs.sh b/scripts/fetch_all_docs.sh
index 7b6c597a..17e5fcec 100755
--- a/scripts/fetch_all_docs.sh
+++ b/scripts/fetch_all_docs.sh
@@ -183,30 +183,32 @@ validate_fetch_result() {
     return 0
 }
 
-# Fetches Oracle Javadoc using an explicit seed list derived from the Javadoc
+# Fetches a manifest-governed Java API using an explicit seed list derived from the Javadoc
 # search indices.  This avoids incomplete recursive crawls that miss pages.
 #
 # Arguments:
-#   $1 - Oracle Javadoc base URL
+#   $1 - Java API Javadoc base URL
 #   $2 - target directory
 #   $3 - human-readable name
 #   $4 - --cut-dirs value
 #   $5 - minimum required HTML files
-#   $6 - whether a validated partial mirror is accepted
-fetch_oracle_javadoc_seed() {
+#   $6 - reject regex (optional)
+#   $7 - whether a validated partial mirror is accepted
+fetch_java_api_javadoc_seed() {
     local url="$1"
     local target_dir="$2"
     local name="$3"
     local cut_dirs="$4"
     local min_files="$5"
-    local partial_mirror_allowed="$6"
+    local reject_regex="${6:-}"
+    local partial_mirror_allowed="$7"
 
     local seed_file="$target_dir/.oracle-javadoc-seed.txt"
-    log "${BLUE}ℹ Oracle Javadoc detected; generating explicit URL seed list...${NC}"
+    log "${BLUE}ℹ Java API Javadoc source; generating explicit URL seed list...${NC}"
     python3 "$SCRIPT_DIR/oracle_javadoc_seed.py" --base-url "$url" --output "$seed_file" 2>&1 | tee -a "$LOG_FILE"
     local seed_url_count
     seed_url_count="$(wc -l "$seed_file" | awk '{print $1}')"
-    log "${BLUE}ℹ Oracle Javadoc seed URLs: $seed_url_count${NC}"
+    log "${BLUE}ℹ Java API Javadoc seed URLs: $seed_url_count${NC}"
 
     local wget_seed_args=(
         --timestamping
@@ -225,6 +227,9 @@ fetch_oracle_javadoc_seed() {
         --retry-connrefused
         --user-agent="java-chat-doc-fetcher/1.0"
     )
+    if [ -n "$reject_regex" ]; then
+        wget_seed_args+=(--reject-regex="$reject_regex")
+    fi
 
     wget "${wget_seed_args[@]}" 2>&1 | tee -a "$LOG_FILE"
     local wget_exit_code=$?
@@ -288,24 +293,27 @@ fetch_docs_mirror() {
 
 # Dispatches documentation fetching: performs pre-fetch housekeeping (existing
 # mirror check, quarantine, legacy cleanup), then delegates to the appropriate
-# strategy — seed-list for Oracle Javadoc, wget --mirror for everything else.
+# strategy — seed-list for manifest-governed Java APIs, wget --mirror for everything else.
 #
-# Arguments (pipe-delimited config row):
-#   $1 - URL
-#   $2 - target directory
-#   $3 - human-readable name
-#   $4 - --cut-dirs value
-#   $5 - minimum required HTML files
-#   $6 - reject regex (optional)
-#   $7 - whether a nonempty partial mirror is retained for incremental reruns
+# Arguments (canonical manifest order):
+#   $1 - Java release, blank only for non-Java documentation
+#   $2 - URL
+#   $3 - relative mirror path beneath DOCS_ROOT
+#   $4 - human-readable name
+#   $5 - --cut-dirs value
+#   $6 - minimum required HTML files
+#   $7 - reject regex (optional)
+#   $8 - whether a nonempty partial mirror is retained for incremental reruns
 fetch_docs() {
-    local url="$1"
-    local target_dir="$2"
-    local name="$3"
-    local cut_dirs="$4"
-    local min_files="$5"
-    local reject_regex="${6:-}"
-    local partial_mirror_allowed="$7"
+    local java_release="$1"
+    local url="$2"
+    local relative_mirror_path="$3"
+    local name="$4"
+    local cut_dirs="$5"
+    local min_files="$6"
+    local reject_regex="${7:-}"
+    local partial_mirror_allowed="$8"
+    local target_dir="$DOCS_ROOT/$relative_mirror_path"
 
     # Allow config-friendly placeholder for regex alternation without breaking our field delimiter.
     reject_regex="${reject_regex//__OR__/|}"
@@ -336,34 +344,72 @@ fetch_docs() {
     cd "$target_dir"
 
     # ── Dispatch to strategy ──
-    if [[ "$url" == *"docs.oracle.com/en/java/javase/"*"/docs/api/" ]]; then
+    if [ -n "$java_release" ]; then
         if [ "$FORCE_REFRESH" != "true" ] && [ "$min_files" -gt 0 ] && [ "$existing_count" -ge "$min_files" ]; then
             log "${GREEN}✓ $name already fetched: $existing_count HTML files (minimum: $min_files)${NC}"
             return 0
         fi
-        fetch_oracle_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$partial_mirror_allowed"
+        fetch_java_api_javadoc_seed "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex" "$partial_mirror_allowed"
     else
         fetch_docs_mirror "$url" "$target_dir" "$name" "$cut_dirs" "$min_files" "$reject_regex" "$partial_mirror_allowed"
     fi
 }
 
-# Projects one seven-field documentation source row into the fetch boundary.
+# Projects one eight-field documentation source row into the fetch boundary.
 fetch_documentation_source() {
     local documentation_source_projection="$1"
     local fetch_projection_delimiters="${documentation_source_projection//[^|]/}"
-    if [ "${#fetch_projection_delimiters}" -ne 6 ]; then
-        log "${RED}✗ Documentation source projection must contain exactly seven fields${NC}"
+    if [ "${#fetch_projection_delimiters}" -ne 7 ]; then
+        log "${RED}✗ Documentation source projection must contain exactly eight fields${NC}"
         return 1
     fi
 
+    local java_release
     local documentation_source_url
-    local mirror_directory
+    local relative_mirror_path
     local documentation_source_name
     local cut_directories
     local minimum_html_files
     local reject_regex
     local partial_mirror_allowed
-    IFS='|' read -r documentation_source_url mirror_directory documentation_source_name cut_directories minimum_html_files reject_regex partial_mirror_allowed <<< "$documentation_source_projection"
+    IFS='|' read -r java_release documentation_source_url relative_mirror_path documentation_source_name cut_directories minimum_html_files reject_regex partial_mirror_allowed <<< "$documentation_source_projection"
+
+    if [ -z "$documentation_source_url" ] || [ -z "$relative_mirror_path" ] || [ -z "$documentation_source_name" ]; then
+        log "${RED}✗ Documentation source projection has a blank required field${NC}"
+        return 1
+    fi
+    if has_boundary_whitespace "$documentation_source_url" \
+        || has_boundary_whitespace "$relative_mirror_path" \
+        || has_boundary_whitespace "$documentation_source_name" \
+        || has_boundary_whitespace "$reject_regex" \
+        || has_manifest_control_character "$documentation_source_url" \
+        || has_manifest_control_character "$relative_mirror_path" \
+        || has_manifest_control_character "$documentation_source_name" \
+        || has_manifest_control_character "$reject_regex"; then
+        log "${RED}✗ Documentation source projection has invalid text fields${NC}"
+        return 1
+    fi
+    if [ -n "$java_release" ] \
+        && { ! is_canonical_manifest_integer "$java_release" || [ "$java_release" = "0" ]; }; then
+        log "${RED}✗ Documentation source Java release must be blank or a positive canonical integer${NC}"
+        return 1
+    fi
+    if ! is_normalized_relative_mirror_path "$relative_mirror_path"; then
+        log "${RED}✗ Documentation source mirror path must be normalized and relative${NC}"
+        return 1
+    fi
+    if [ -n "$java_release" ] && ! is_absolute_https_remote_base_url "$documentation_source_url"; then
+        log "${RED}✗ Java API documentation source URL must be an absolute HTTPS base URL${NC}"
+        return 1
+    fi
+    if ! is_canonical_manifest_integer "$cut_directories"; then
+        log "${RED}✗ Documentation source cut-directories value must be a canonical integer${NC}"
+        return 1
+    fi
+    if ! is_canonical_manifest_integer "$minimum_html_files" || [ "$minimum_html_files" = "0" ]; then
+        log "${RED}✗ Documentation source minimum HTML files must be a positive canonical integer${NC}"
+        return 1
+    fi
 
     if [ "$partial_mirror_allowed" != "true" ] && [ "$partial_mirror_allowed" != "false" ]; then
         log "${RED}✗ Documentation source partial-mirror policy must be true or false${NC}"
@@ -373,9 +419,9 @@ fetch_documentation_source() {
     echo ""
     log "Processing: $documentation_source_name"
     log "URL: $documentation_source_url"
-    log "Target: $mirror_directory"
+    log "Target: $DOCS_ROOT/$relative_mirror_path"
 
-    fetch_docs "$documentation_source_url" "$mirror_directory" "$documentation_source_name" "$cut_directories" "$minimum_html_files" "$reject_regex" "$partial_mirror_allowed"
+    fetch_docs "$java_release" "$documentation_source_url" "$relative_mirror_path" "$documentation_source_name" "$cut_directories" "$minimum_html_files" "$reject_regex" "$partial_mirror_allowed"
 }
 
 run_documentation_fetch() {
@@ -386,32 +432,33 @@ fi
 parse_fetch_arguments "$@"
 
 # Documentation sources configuration
-# Format: URL|TARGET_DIR|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX|ALLOW_PARTIAL
+# Format: JAVA_RELEASE|URL|RELATIVE_MIRROR_PATH|NAME|CUT_DIRS|MIN_FILES|REJECT_REGEX|ALLOW_PARTIAL
+# JAVA_RELEASE is blank for non-Java documentation sources.
 DOC_SOURCES=(
     # Spring Boot (current)
-    "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot-complete|Spring Boot Reference (current)|1|50||false"
-    "${SPRING_BOOT_API_BASE:-https://docs.spring.io/spring-boot/api/}|$DOCS_ROOT/spring-boot-complete|Spring Boot API (current)|1|7000||false"
+    "|${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|spring-boot-complete|Spring Boot Reference (current)|1|50||false"
+    "|${SPRING_BOOT_API_BASE:-https://docs.spring.io/spring-boot/api/}|spring-boot-complete|Spring Boot API (current)|1|7000||false"
 
     # Spring AI
     # Stable reference (1.1.x) - avoid pulling versioned reference subtrees (including 2.0) and SNAPSHOT content.
-    "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai-reference|Spring AI Reference (stable)|1|80|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
+    "|${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|spring-ai-reference|Spring AI Reference (stable)|1|80|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
     # 2.0 reference (milestone) - avoid SNAPSHOT content.
-    "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-reference-2|Spring AI Reference (2.0)|1|80|/spring-ai/reference/[^/]*SNAPSHOT|false"
+    "|${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|spring-ai-reference-2|Spring AI Reference (2.0)|1|80|/spring-ai/reference/[^/]*SNAPSHOT|false"
     # API docs (stable + 2.x). Keep these separate to avoid quarantine/validation conflicts.
-    "${SPRING_AI_API_STABLE_BASE:-https://docs.spring.io/spring-ai/docs/current/api/}|$DOCS_ROOT/spring-ai-api-stable|Spring AI API (stable)|1|200||false"
-    "${SPRING_AI_API_2_BASE:-https://docs.spring.io/spring-ai/docs/2.0.x/api/}|$DOCS_ROOT/spring-ai-api-2|Spring AI API (2.x)|1|200||false"
+    "|${SPRING_AI_API_STABLE_BASE:-https://docs.spring.io/spring-ai/docs/current/api/}|spring-ai-api-stable|Spring AI API (stable)|1|200||false"
+    "|${SPRING_AI_API_2_BASE:-https://docs.spring.io/spring-ai/docs/2.0.x/api/}|spring-ai-api-2|Spring AI API (2.x)|1|200||false"
 
     # Spring Framework (current) - avoid pulling older reference versions under /reference/6.x, etc.
-    "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Reference (current)|1|3000|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
-    "${SPRING_FRAMEWORK_API_BASE:-https://docs.spring.io/spring-framework/docs/current/javadoc-api/}|$DOCS_ROOT/spring-framework-complete|Spring Framework Javadoc (current)|1|7000||false"
+    "|${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|spring-framework-complete|Spring Framework Reference (current)|1|3000|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
+    "|${SPRING_FRAMEWORK_API_BASE:-https://docs.spring.io/spring-framework/docs/current/javadoc-api/}|spring-framework-complete|Spring Framework Javadoc (current)|1|7000||false"
 
-    "${JAVA25_RELEASE_NOTES_ISSUES_URL:-https://www.oracle.com/java/technologies/javase/25-relnote-issues.html}|$DOCS_ROOT/oracle/javase|Java 25 Release Notes Issues|3|1||false"
-    "${IBM_JAVA25_ARTICLE_URL:-https://developer.ibm.com/articles/java-whats-new-java25/}|$DOCS_ROOT/ibm/articles|IBM Java 25 Overview|1|1||false"
-    "${JETBRAINS_JAVA25_BLOG_URL:-https://blog.jetbrains.com/idea/2025/09/java-25-lts-and-intellij-idea/}|$DOCS_ROOT/jetbrains/idea/2025/09|JetBrains Java 25 Blog|3|1||false"
+    "|${JAVA25_RELEASE_NOTES_ISSUES_URL:-https://www.oracle.com/java/technologies/javase/25-relnote-issues.html}|oracle/javase|Java 25 Release Notes Issues|3|1||false"
+    "|${IBM_JAVA25_ARTICLE_URL:-https://developer.ibm.com/articles/java-whats-new-java25/}|ibm/articles|IBM Java 25 Overview|1|1||false"
+    "|${JETBRAINS_JAVA25_BLOG_URL:-https://blog.jetbrains.com/idea/2025/09/java-25-lts-and-intellij-idea/}|jetbrains/idea/2025/09|JetBrains Java 25 Blog|3|1||false"
 )
 
 load_java_api_documentation_sources "$JAVA_API_SOURCES_MANIFEST"
-append_java_api_fetch_sources "$DOCS_ROOT"
+append_java_api_fetch_sources
 
 if [ "$LIST_JAVA_API_SOURCES" = "true" ]; then
     printf '%s\n' "${JAVA_API_SOURCE_PROJECTIONS[@]}"
@@ -420,10 +467,10 @@ fi
 
 if [ "$INCLUDE_QUICK" = "true" ]; then
     DOC_SOURCES+=(
-        "${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|$DOCS_ROOT/spring-boot|Spring Boot Quick (reference landing)|1|1||false"
-        "${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|$DOCS_ROOT/spring-framework|Spring Framework Quick (reference landing)|1|1|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
-        "${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|$DOCS_ROOT/spring-ai|Spring AI Quick (reference landing)|1|1|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
-        "${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|$DOCS_ROOT/spring-ai-2|Spring AI Quick (2.0 landing)|1|1|/spring-ai/reference/[^/]*SNAPSHOT|false"
+        "|${SPRING_BOOT_REFERENCE_BASE:-https://docs.spring.io/spring-boot/reference/}|spring-boot|Spring Boot Quick (reference landing)|1|1||false"
+        "|${SPRING_FRAMEWORK_REFERENCE_BASE:-https://docs.spring.io/spring-framework/reference/}|spring-framework|Spring Framework Quick (reference landing)|1|1|/spring-framework/reference/[0-9]__OR__/spring-framework/reference/[^/]*SNAPSHOT|false"
+        "|${SPRING_AI_REFERENCE_BASE:-https://docs.spring.io/spring-ai/reference/}|spring-ai|Spring AI Quick (reference landing)|1|1|/spring-ai/reference/[0-9]__OR__/spring-ai/reference/[^/]*SNAPSHOT|false"
+        "|${SPRING_AI_REFERENCE_2_BASE:-https://docs.spring.io/spring-ai/reference/2.0/}|spring-ai-2|Spring AI Quick (2.0 landing)|1|1|/spring-ai/reference/[^/]*SNAPSHOT|false"
     )
 fi
 

From e08ed9d6e08a89ffe40b62c7fbdb5ee776763092 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:06 -0700
Subject: [PATCH 32/40] test(docs): enforce complete Java API fetch parity

---
 scripts/test_java_api_fetch_projection.sh | 119 +++++++++++++++-------
 1 file changed, 83 insertions(+), 36 deletions(-)

diff --git a/scripts/test_java_api_fetch_projection.sh b/scripts/test_java_api_fetch_projection.sh
index d28aa76b..5b6ec80c 100755
--- a/scripts/test_java_api_fetch_projection.sh
+++ b/scripts/test_java_api_fetch_projection.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Verifies that canonical Java API manifest rows retain their seven-field fetch projection.
+# Verifies that canonical Java API manifest rows retain their eight-field fetch projection.
 
 set -euo pipefail
 
@@ -33,7 +33,7 @@ fetch_docs() {
 JAVA_API_SOURCE_PROJECTIONS=()
 load_java_api_documentation_sources "$JAVA_API_SOURCES_MANIFEST"
 DOC_SOURCES=()
-append_java_api_fetch_sources "$TEST_DOCS_ROOT"
+append_java_api_fetch_sources
 
 if [ "${#JAVA_API_SOURCE_PROJECTIONS[@]}" -ne "${#DOC_SOURCES[@]}" ]; then
     fail_java_api_fetch_projection_test "fetch projections did not preserve the complete manifest order"
@@ -43,41 +43,63 @@ for java_api_source_index in "${!JAVA_API_SOURCE_PROJECTIONS[@]}"; do
     manifest_projection="${JAVA_API_SOURCE_PROJECTIONS[$java_api_source_index]}"
     documentation_fetch_projection="${DOC_SOURCES[$java_api_source_index]}"
     fetch_projection_delimiters="${documentation_fetch_projection//[^|]/}"
-    if [ "${#fetch_projection_delimiters}" -ne 6 ]; then
-        fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index must contain exactly seven fields"
+    if [ "${#fetch_projection_delimiters}" -ne 7 ]; then
+        fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index must contain exactly eight fields"
     fi
 
-    manifest_projection_without_release="${manifest_projection#*|}"
-    expected_remote_base_url="${manifest_projection_without_release%%|*}"
-    manifest_projection_after_remote_base_url="${manifest_projection_without_release#*|}"
-    expected_relative_mirror_path="${manifest_projection_after_remote_base_url%%|*}"
-    expected_fetch_projection="$expected_remote_base_url|$TEST_DOCS_ROOT/$expected_relative_mirror_path|${manifest_projection_after_remote_base_url#*|}"
-    if [ "$documentation_fetch_projection" != "$expected_fetch_projection" ]; then
+    if [ "$documentation_fetch_projection" != "$manifest_projection" ]; then
         fail_java_api_fetch_projection_test "Java API fetch projection at index $java_api_source_index diverged from the canonical manifest row"
     fi
 
     fetch_execution_arguments=()
     fetch_documentation_source "$documentation_fetch_projection" > /dev/null
-    if [ "${#fetch_execution_arguments[@]}" -ne 7 ]; then
-        fail_java_api_fetch_projection_test "Java API fetch execution at index $java_api_source_index must receive exactly seven fields"
+    if [ "${#fetch_execution_arguments[@]}" -ne 8 ]; then
+        fail_java_api_fetch_projection_test "Java API fetch execution at index $java_api_source_index must receive exactly eight fields"
     fi
 
     actual_fetch_projection="$(IFS='|'; printf '%s' "${fetch_execution_arguments[*]}")"
-    if [ "$actual_fetch_projection" != "$documentation_fetch_projection" ]; then
+    if [ "$actual_fetch_projection" != "$manifest_projection" ]; then
         fail_java_api_fetch_projection_test "Java API fetch execution at index $java_api_source_index diverged from the appended projection"
     fi
 
     expected_allow_partial="${manifest_projection##*|}"
     manifest_projection_without_allow_partial="${manifest_projection%|*}"
     expected_reject_regex="${manifest_projection_without_allow_partial##*|}"
-    if [ "${fetch_execution_arguments[5]}" != "$expected_reject_regex" ]; then
+    if [ "${fetch_execution_arguments[6]}" != "$expected_reject_regex" ]; then
         fail_java_api_fetch_projection_test "Java API reject regex at index $java_api_source_index was not projected separately"
     fi
-    if [ "${fetch_execution_arguments[6]}" != "$expected_allow_partial" ]; then
+    if [ "${fetch_execution_arguments[7]}" != "$expected_allow_partial" ]; then
         fail_java_api_fetch_projection_test "Java API partial-mirror policy at index $java_api_source_index was not projected separately"
     fi
 done
 
+generic_fetch_projection="|https://example.invalid/reference.html|generic/reference|Generic Reference|1|1||false"
+fetch_execution_arguments=()
+fetch_documentation_source "$generic_fetch_projection" > /dev/null
+if [ "${#fetch_execution_arguments[@]}" -ne 8 ] \
+    || [ -n "${fetch_execution_arguments[0]}" ] \
+    || [ -n "${fetch_execution_arguments[6]}" ]; then
+    fail_java_api_fetch_projection_test "generic projection did not preserve empty Java-release and reject-regex fields"
+fi
+
+fetch_execution_arguments=()
+if fetch_documentation_source "https://example.invalid/|generic|Generic|1|1||false" > /dev/null; then
+    fail_java_api_fetch_projection_test "legacy seven-field projection was accepted"
+fi
+if [ "${#fetch_execution_arguments[@]}" -ne 0 ]; then
+    fail_java_api_fetch_projection_test "invalid seven-field projection reached fetch execution"
+fi
+
+for invalid_relative_mirror_path in "../outside" "/absolute" 'backslash\path'; do
+    fetch_execution_arguments=()
+    if fetch_documentation_source "|https://example.invalid/|$invalid_relative_mirror_path|Invalid path|1|1||false" > /dev/null; then
+        fail_java_api_fetch_projection_test "unsafe mirror path reached fetch execution: $invalid_relative_mirror_path"
+    fi
+    if [ "${#fetch_execution_arguments[@]}" -ne 0 ]; then
+        fail_java_api_fetch_projection_test "unsafe mirror path invoked fetch execution: $invalid_relative_mirror_path"
+    fi
+done
+
 set --
 # shellcheck source=fetch_all_docs.sh
 source "$FETCH_SCRIPT"
@@ -127,70 +149,95 @@ quarantine_capture_file="$TEST_DOCS_ROOT/quarantine.log"
 quarantine_incomplete_dir() {
     printf 'quarantined\n' >> "$quarantine_capture_file"
 }
+generic_dispatch_capture_file="$TEST_DOCS_ROOT/generic-dispatch"
 fetch_docs_mirror() {
+    printf '%s|%s|%s\n' "$1" "$2" "$7" > "$generic_dispatch_capture_file"
     return 0
 }
 
-if ! (fetch_docs "https://example.com/api/" "$TEST_DOCS_ROOT/partial" "Partial mirror" 1 10 "" true); then
+DOCS_ROOT="$TEST_DOCS_ROOT"
+if ! (fetch_docs "" "https://example.com/api/" "partial" "Partial mirror" 1 10 "" true); then
     fail_java_api_fetch_projection_test "allowPartial=true fetch dispatch failed"
 fi
 if [ -s "$quarantine_capture_file" ]; then
     fail_java_api_fetch_projection_test "allowPartial=true quarantined an incremental mirror"
 fi
-if ! (fetch_docs "https://example.com/api/" "$TEST_DOCS_ROOT/complete-required" "Complete mirror" 1 10 "" false); then
+if ! (fetch_docs "" "https://example.com/api/" "complete-required" "Complete mirror" 1 10 "" false); then
     fail_java_api_fetch_projection_test "allowPartial=false fetch dispatch failed"
 fi
 if [ ! -s "$quarantine_capture_file" ]; then
     fail_java_api_fetch_projection_test "allowPartial=false did not quarantine an incomplete mirror"
 fi
 
-oracle_dispatch_capture_file="$TEST_DOCS_ROOT/oracle-dispatch-policy"
-fetch_oracle_javadoc_seed() {
-    printf '%s\n' "$6" > "$oracle_dispatch_capture_file"
+java_api_dispatch_capture_file="$TEST_DOCS_ROOT/java-api-dispatch"
+fetch_java_api_javadoc_seed() {
+    printf '%s|%s|%s\n' "$1" "$6" "$7" > "$java_api_dispatch_capture_file"
 }
 if ! (fetch_docs \
-    "https://docs.oracle.com/en/java/javase/21/docs/api/" \
-    "$TEST_DOCS_ROOT/oracle-dispatch" \
+    "21" \
+    "https://example.invalid/javadoc/" \
+    "java/java21-complete" \
     "Java 21 API" \
     5 \
     10 \
     "" \
     true); then
-    fail_java_api_fetch_projection_test "Oracle Javadoc fetch dispatch failed"
+    fail_java_api_fetch_projection_test "manifest-governed Java API fetch dispatch failed"
+fi
+if [ "$(cat "$java_api_dispatch_capture_file")" != "https://example.invalid/javadoc/||true" ]; then
+    fail_java_api_fetch_projection_test "Java API dispatch did not preserve manifest identity independently of URL host"
+fi
+
+if ! (fetch_docs \
+    "" \
+    "https://docs.oracle.com/en/java/javase/21/docs/api/" \
+    "generic/oracle-shaped-url" \
+    "Generic Oracle-shaped URL" \
+    5 \
+    10 \
+    "" \
+    true); then
+    fail_java_api_fetch_projection_test "generic source with an Oracle-shaped URL failed mirror dispatch"
 fi
-if [ "$(cat "$oracle_dispatch_capture_file")" != "true" ]; then
-    fail_java_api_fetch_projection_test "Oracle Javadoc dispatch dropped the partial-mirror policy"
+if [ "$(cat "$generic_dispatch_capture_file")" != "https://docs.oracle.com/en/java/javase/21/docs/api/|$TEST_DOCS_ROOT/generic/oracle-shaped-url|true" ]; then
+    fail_java_api_fetch_projection_test "URL text overrode blank Java API identity"
 fi
 
 set --
 # shellcheck source=fetch_all_docs.sh
 source "$FETCH_SCRIPT"
 
-LOG_FILE="$TEST_DOCS_ROOT/oracle-seed-fetch.log"
-oracle_validation_capture_file="$TEST_DOCS_ROOT/oracle-validation-policy"
+LOG_FILE="$TEST_DOCS_ROOT/java-api-seed-fetch.log"
+java_api_validation_capture_file="$TEST_DOCS_ROOT/java-api-validation-policy"
+java_api_wget_arguments_capture_file="$TEST_DOCS_ROOT/java-api-wget-arguments"
 python3() {
     : > "$5"
 }
 wget() {
+    printf '%s\n' "$@" > "$java_api_wget_arguments_capture_file"
     return 0
 }
 validate_fetch_result() {
-    printf '%s\n' "$5" > "$oracle_validation_capture_file"
+    printf '%s\n' "$5" > "$java_api_validation_capture_file"
 }
 
-mkdir -p "$TEST_DOCS_ROOT/oracle-validation"
-if ! (cd "$TEST_DOCS_ROOT/oracle-validation" \
-    && fetch_oracle_javadoc_seed \
+mkdir -p "$TEST_DOCS_ROOT/java-api-validation"
+if ! (cd "$TEST_DOCS_ROOT/java-api-validation" \
+    && fetch_java_api_javadoc_seed \
         "https://docs.oracle.com/en/java/javase/21/docs/api/" \
-        "$TEST_DOCS_ROOT/oracle-validation" \
+        "$TEST_DOCS_ROOT/java-api-validation" \
         "Java 21 API" \
         5 \
         10 \
+        "excluded-path" \
         true); then
-    fail_java_api_fetch_projection_test "Oracle Javadoc validation boundary failed"
+    fail_java_api_fetch_projection_test "Java API Javadoc validation boundary failed"
+fi
+if [ "$(cat "$java_api_validation_capture_file")" != "true" ]; then
+    fail_java_api_fetch_projection_test "Java API Javadoc validation dropped the partial-mirror policy"
 fi
-if [ "$(cat "$oracle_validation_capture_file")" != "true" ]; then
-    fail_java_api_fetch_projection_test "Oracle Javadoc validation dropped the partial-mirror policy"
+if ! grep -Fxq -- '--reject-regex=excluded-path' "$java_api_wget_arguments_capture_file"; then
+    fail_java_api_fetch_projection_test "Java API seed fetch dropped the manifest reject regex"
 fi
 
 run_summary_capture_file="$TEST_DOCS_ROOT/run-summary"
@@ -211,4 +258,4 @@ if [ "$aggregated_fetched_count" -ne 0 ] || [ "$aggregated_partial_count" -le 0
     fail_java_api_fetch_projection_test "a full fetch run did not aggregate retained partial mirrors separately from failures"
 fi
 
-printf 'PASS: Java API fetch projections preserve partial mirrors without reporting completion.\n'
+printf 'PASS: Java API fetch projections preserve all eight manifest fields and partial-mirror semantics.\n'

From e61968f14858f803b0586963df9dd5f4f3e8bb64 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:06 -0700
Subject: [PATCH 33/40] test(config): reject unsafe Java API manifest values

---
 .../config/JavaApiDocumentationManifestTest.java       | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
index 2453bade..f5b1caac 100644
--- a/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
+++ b/src/test/java/com/williamcallahan/javachat/config/JavaApiDocumentationManifestTest.java
@@ -56,10 +56,20 @@ void rejectsSharedInvalidManifestFixturesInJavaAndBash() throws IOException, Int
                                 .get(1)
                                 .substring(0, canonicalManifestLines.get(1).lastIndexOf('|'))),
                 withColumn(canonicalManifestLines, 1, 1, " https://docs.oracle.com/invalid/"),
+                withColumn(canonicalManifestLines, 1, 1, "http://example.invalid/invalid/"),
+                withColumn(canonicalManifestLines, 1, 1, "https:///invalid/"),
+                withColumn(canonicalManifestLines, 1, 1, "https://example.invalid/invalid"),
                 withColumn(canonicalManifestLines, 1, 2, ""),
+                withColumn(canonicalManifestLines, 1, 2, "java/./java21-complete"),
+                withColumn(canonicalManifestLines, 1, 2, "java/../java21-complete"),
+                withColumn(canonicalManifestLines, 1, 2, "/java/java21-complete"),
+                withColumn(canonicalManifestLines, 1, 2, "java\\java21-complete"),
+                withColumn(canonicalManifestLines, 1, 2, "java//java21-complete"),
                 withColumn(canonicalManifestLines, 1, 4, "+5"),
                 withColumn(canonicalManifestLines, 1, 4, "05"),
                 withColumn(canonicalManifestLines, 1, 5, "2147483648"),
+                withColumn(canonicalManifestLines, 1, 6, "\u0001"),
+                withColumn(canonicalManifestLines, 1, 6, " reject-pattern"),
                 withColumn(canonicalManifestLines, 1, 7, "TRUE"),
                 withDuplicateRelease(canonicalManifestLines),
                 withDuplicateMirrorPath(canonicalManifestLines));

From b95c521b1f7d95bc2b123573e71675415b89af91 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:07 -0700
Subject: [PATCH 34/40] test(ingestion): reject Java API selector aliases

---
 .../JavaApiDocumentationSourceParityTest.java | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
index 0e37992b..e75dba9e 100644
--- a/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
+++ b/src/test/java/com/williamcallahan/javachat/cli/JavaApiDocumentationSourceParityTest.java
@@ -2,6 +2,7 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.williamcallahan.javachat.config.DocsSourceRegistry;
 import com.williamcallahan.javachat.config.DocsSourceRegistry.JavaApiDocumentationSource;
@@ -10,6 +11,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.List;
+import java.util.Locale;
 import java.util.Set;
 import org.junit.jupiter.api.Test;
 
@@ -18,7 +20,7 @@
  */
 class JavaApiDocumentationSourceParityTest {
 
-    private static final Set<String> LEGACY_QUICK_JAVA_DOCSET_TOKENS = Set.of("java24", "java25");
+    private static final String LEGACY_JAVA_QUICK_SELECTOR_PREFIX = "java";
 
     @Test
     void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOException, InterruptedException {
@@ -32,8 +34,6 @@ void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOExce
                 .toList();
 
         assertEquals(expectedCliDocumentationSets, actualCliDocumentationSets);
-        assertFalse(DocumentationSetCatalog.allSets().stream()
-                .anyMatch(documentationSet -> documentationSet.matchesAny(LEGACY_QUICK_JAVA_DOCSET_TOKENS)));
 
         Path fetchScriptPath = Path.of("scripts", "fetch_all_docs.sh").toAbsolutePath();
         ProcessBuilder fetchSourceListingCommand =
@@ -71,4 +71,41 @@ void projectsCanonicalJavaApiSourcesIntoCliCatalogAndFetchScript() throws IOExce
 
         assertEquals(0, fetchProjectionTestExitCode, fetchProjectionTestOutput);
     }
+
+    @Test
+    void acceptsOnlyCanonicalRelativeMirrorPathsForManifestBackedJavaApiSets() {
+        for (JavaApiDocumentationSource javaApiDocumentationSource : DocsSourceRegistry.javaApiDocumentationSources()) {
+            DocumentationSet catalogDocumentationSet = DocumentationSetCatalog.allSets().stream()
+                    .filter(documentationSet ->
+                            documentationSet.relativePath().equals(javaApiDocumentationSource.relativeMirrorPath()))
+                    .findFirst()
+                    .orElseThrow();
+
+            String canonicalRelativeMirrorPath = javaApiDocumentationSource.relativeMirrorPath();
+            assertEquals(canonicalRelativeMirrorPath, catalogDocumentationSet.primarySelector());
+            assertTrue(catalogDocumentationSet.matchesSelectorTokens(Set.of(canonicalRelativeMirrorPath)));
+
+            List<String> prohibitedSelectorAliases = List.of(
+                    javaApiDocumentationSource.displayName(),
+                    canonicalRelativeMirrorPath.replace('/', '-'),
+                    javaApiDocumentationSource.javaRelease(),
+                    LEGACY_JAVA_QUICK_SELECTOR_PREFIX + javaApiDocumentationSource.javaRelease(),
+                    canonicalRelativeMirrorPath.toUpperCase(Locale.ROOT));
+            for (String prohibitedSelectorAlias : prohibitedSelectorAliases) {
+                assertFalse(
+                        catalogDocumentationSet.matchesSelectorTokens(Set.of(prohibitedSelectorAlias)),
+                        "Canonical Java API selector accepted alias " + prohibitedSelectorAlias);
+            }
+        }
+    }
+
+    @Test
+    void preservesEstablishedSelectorsForNonJavaDocumentationSets() {
+        DocumentationSet quickDocumentationSet =
+                DocumentationSetCatalog.quickSets().getFirst();
+
+        assertEquals(quickDocumentationSet.relativePath().replace('/', '-'), quickDocumentationSet.primarySelector());
+        assertTrue(quickDocumentationSet.matchesSelectorTokens(
+                Set.of(quickDocumentationSet.displayName().toUpperCase(Locale.ROOT))));
+    }
 }

From 502bc8a3c02db3cd70813e90ab8ac2f110602a4b Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:09 -0700
Subject: [PATCH 35/40] test(provider): cover wrapped OkHttp call timeouts

---
 .../OpenAiProviderRoutingServiceTest.java     | 44 ++++++++++++++++---
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java
index a73b6a28..32c00559 100644
--- a/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/OpenAiProviderRoutingServiceTest.java
@@ -25,6 +25,9 @@
  */
 class OpenAiProviderRoutingServiceTest {
     private static final long PRIMARY_BACKOFF_SECONDS = 600L;
+    private static final String OPENAI_REQUEST_FAILED_MESSAGE = "Request failed";
+    private static final String OK_HTTP_CALL_TIMEOUT_MESSAGE = "timeout";
+    private static final String CALLER_INTERRUPTION_MESSAGE = "request interrupted by caller timeout";
 
     private OpenAiProviderRoutingService createRoutingService() {
         RateLimitService rateLimitService = mock(RateLimitService.class);
@@ -40,12 +43,31 @@ void shouldBackoffPrimaryTreatsSdkIoAsBackoffEligible() {
     }
 
     @Test
-    void shouldBackoffPrimaryIgnoresCallerCancellationWrappedBySdkIo() {
+    void shouldBackoffPrimaryIgnoresWrappedCallerInterruption() {
         OpenAiProviderRoutingService routingService = createRoutingService();
-        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
-        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
 
-        assertFalse(routingService.shouldBackoffPrimary(cancelledCompletion));
+        assertFalse(routingService.shouldBackoffPrimary(wrappedCallerInterruption()));
+    }
+
+    @Test
+    void shouldBackoffPrimaryTreatsWrappedOkHttpCallTimeoutAsBackoffEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertTrue(routingService.shouldBackoffPrimary(wrappedOkHttpCallTimeout()));
+    }
+
+    @Test
+    void streamingFallbackEligibilityTreatsWrappedOkHttpCallTimeoutAsEligible() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertTrue(routingService.isStreamingFallbackEligible(wrappedOkHttpCallTimeout()));
+    }
+
+    @Test
+    void recoverableStreamingFailureTreatsWrappedOkHttpCallTimeoutAsRetryable() {
+        OpenAiProviderRoutingService routingService = createRoutingService();
+
+        assertTrue(routingService.isRecoverableStreamingFailure(wrappedOkHttpCallTimeout()));
     }
 
     @Test
@@ -59,10 +81,8 @@ void callerCancellationKeepsConfiguredPrimaryProviderEligible() {
                 rateLimitService, PRIMARY_BACKOFF_SECONDS, RateLimitService.ApiProvider.OPENAI.getName());
         OpenAIClient openAiClient = mock(OpenAIClient.class);
         OpenAIClient githubModelsClient = mock(OpenAIClient.class);
-        InterruptedIOException interruptedRequest = new InterruptedIOException("request interrupted by caller timeout");
-        OpenAIIoException cancelledCompletion = new OpenAIIoException("Request failed", interruptedRequest);
 
-        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, cancelledCompletion);
+        routingService.recordProviderFailure(RateLimitService.ApiProvider.OPENAI, wrappedCallerInterruption());
 
         List<OpenAiProviderCandidate> availableProviders =
                 routingService.selectAvailableProviderCandidates(githubModelsClient, openAiClient);
@@ -188,4 +208,14 @@ void primaryBackoffUsesConfiguredAlternateProviderWhenAvailable() {
                 RateLimitService.ApiProvider.GITHUB_MODELS,
                 availableProviders.get(0).provider());
     }
+
+    private OpenAIIoException wrappedOkHttpCallTimeout() {
+        return new OpenAIIoException(
+                OPENAI_REQUEST_FAILED_MESSAGE, new InterruptedIOException(OK_HTTP_CALL_TIMEOUT_MESSAGE));
+    }
+
+    private OpenAIIoException wrappedCallerInterruption() {
+        return new OpenAIIoException(
+                OPENAI_REQUEST_FAILED_MESSAGE, new InterruptedIOException(CALLER_INTERRUPTION_MESSAGE));
+    }
 }

From da3a1aacaf4de63d851441811b7313b6222bf722 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:11 -0700
Subject: [PATCH 36/40] test(retrieval): preserve redacted citation identity

---
 .../service/RetrievalServiceTest.java         | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
index 8bc0aeb0..44dfcdbc 100644
--- a/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
+++ b/src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java
@@ -115,23 +115,25 @@ void preservesDistinctSamePageChunksForRerankingAndDeduplicatesTheirCitations()
     }
 
     @Test
-    void preservesDistinctUnmappedLocalDocumentsWithoutContentHashes() {
+    void keepsDistinctUnmappedLocalDocumentsAndRedactsTheirCitations() {
         HybridSearchService hybridSearchService = mock(HybridSearchService.class);
         RerankerService rerankerService = mock(RerankerService.class);
         DocumentFactory documentFactory = mock(DocumentFactory.class);
         AppProperties appProperties = new AppProperties();
         RetrievalService retrievalService =
                 new RetrievalService(hybridSearchService, appProperties, rerankerService, documentFactory);
+        String firstUnmappedLocalUrl = "file:///unmapped/first.html";
+        String secondUnmappedLocalUrl = "file:///unmapped/second.html";
 
         Document firstUnmappedLocalDocument = Document.builder()
                 .id("first-unmapped-local")
                 .text("First local document")
-                .metadata("url", "file:///unmapped/first.html")
+                .metadata("url", firstUnmappedLocalUrl)
                 .build();
         Document secondUnmappedLocalDocument = Document.builder()
                 .id("second-unmapped-local")
                 .text("Second local document")
-                .metadata("url", "file:///unmapped/second.html")
+                .metadata("url", secondUnmappedLocalUrl)
                 .build();
         List<Document> retrievalCandidates = List.of(firstUnmappedLocalDocument, secondUnmappedLocalDocument);
         when(hybridSearchService.searchOutcome(anyString(), anyInt(), any(RetrievalConstraint.class)))
@@ -142,8 +144,20 @@ void preservesDistinctUnmappedLocalDocumentsWithoutContentHashes() {
         });
 
         RetrievalService.RetrievalOutcome retrievalOutcome = retrievalService.retrieveOutcome("Local documentation");
+        RetrievalService.CitationOutcome citationOutcome = retrievalService.toCitations(retrievalOutcome.documents());
+        String redactedLocalCitationUrl = DocsSourceRegistry.normalizeDocUrl(firstUnmappedLocalUrl);
 
         assertEquals(retrievalCandidates, retrievalOutcome.documents());
+        assertEquals(2, citationOutcome.citations().size());
+        assertEquals(
+                List.of(redactedLocalCitationUrl, redactedLocalCitationUrl),
+                citationOutcome.citations().stream()
+                        .map(citation -> citation.getUrl())
+                        .toList());
+        assertTrue(citationOutcome.citations().stream()
+                .map(citation -> citation.getUrl())
+                .noneMatch(citationUrl -> citationUrl.contains("/unmapped/")));
+        assertEquals(0, citationOutcome.failedConversionCount());
     }
 
     @Test

From aaec1e10390038ef6049e31525d507daa805b046 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:12 -0700
Subject: [PATCH 37/40] test(security): verify secure CSRF cookie lifecycle

---
 .../javachat/config/SecurityConfigTest.java   | 48 ++++++++++++++++---
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
index 11cbe0ed..cd0c0ea7 100644
--- a/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
+++ b/src/test/java/com/williamcallahan/javachat/config/SecurityConfigTest.java
@@ -4,6 +4,7 @@
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
@@ -34,7 +35,10 @@ class SecurityConfigTest {
     private static final String LOGOUT_ENDPOINT = "/logout";
     private static final String CSRF_COOKIE_NAME = "XSRF-TOKEN";
     private static final String CSRF_HEADER_NAME = "X-XSRF-TOKEN";
+    private static final String CSRF_COOKIE_ROOT_PATH = "/";
+    private static final String CSRF_COOKIE_SAME_SITE_ATTRIBUTE = "SameSite";
     private static final String CSRF_COOKIE_SAME_SITE_POLICY = "Lax";
+    private static final int CSRF_COOKIE_DELETION_MAX_AGE_SECONDS = 0;
     private static final String CSRF_INVALID_MESSAGE =
             "CSRF token missing or invalid. Refresh the page and retry the request.";
 
@@ -46,8 +50,7 @@ void acceptsCookieAndHeaderTokenWithoutServerSession() throws Exception {
         MvcResult csrfRefreshExchange = requestCsrfCookie();
         Cookie csrfCookie = csrfRefreshExchange.getResponse().getCookie(CSRF_COOKIE_NAME);
         assertNotNull(csrfCookie);
-        assertEquals(CSRF_COOKIE_SAME_SITE_POLICY, csrfCookie.getAttribute("SameSite"));
-        assertFalse(csrfCookie.isHttpOnly());
+        assertBrowserReadableCsrfCookieAttributes(csrfCookie);
         assertNull(csrfRefreshExchange.getRequest().getSession(false));
         assertNull(csrfRefreshExchange.getResponse().getCookie("JSESSIONID"));
 
@@ -69,6 +72,15 @@ void returnsJsonWhenCsrfTokenIsMissing() throws Exception {
                 .andExpect(jsonPath("$.message").value(CSRF_INVALID_MESSAGE));
     }
 
+    @Test
+    void issuesSecureBrowserReadableCsrfCookieOverHttps() throws Exception {
+        Cookie issuedCsrfCookie = requestSecureCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(issuedCsrfCookie);
+
+        assertTrue(issuedCsrfCookie.getSecure());
+        assertBrowserReadableCsrfCookieAttributes(issuedCsrfCookie);
+    }
+
     @Test
     void rejectsMismatchedAndSingleSidedCsrfTokens() throws Exception {
         Cookie csrfCookie = requestCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
@@ -89,17 +101,21 @@ void rejectsMismatchedAndSingleSidedCsrfTokens() throws Exception {
 
     @Test
     void deletesCsrfCookieImmediatelyOnLogout() throws Exception {
-        Cookie csrfCookie = requestCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
-        assertNotNull(csrfCookie);
+        Cookie issuedCsrfCookie = requestSecureCsrfCookie().getResponse().getCookie(CSRF_COOKIE_NAME);
+        assertNotNull(issuedCsrfCookie);
 
-        MvcResult logoutExchange = mockMvc.perform(
-                        post(LOGOUT_ENDPOINT).cookie(csrfCookie).header(CSRF_HEADER_NAME, csrfCookie.getValue()))
+        MvcResult logoutExchange = mockMvc.perform(post(LOGOUT_ENDPOINT)
+                        .secure(true)
+                        .cookie(issuedCsrfCookie)
+                        .header(CSRF_HEADER_NAME, issuedCsrfCookie.getValue()))
                 .andExpect(status().is3xxRedirection())
                 .andReturn();
 
         Cookie deletedCsrfCookie = logoutExchange.getResponse().getCookie(CSRF_COOKIE_NAME);
         assertNotNull(deletedCsrfCookie);
-        assertEquals(0, deletedCsrfCookie.getMaxAge());
+        assertTrue(deletedCsrfCookie.getSecure());
+        assertBrowserReadableCsrfCookieAttributes(deletedCsrfCookie);
+        assertEquals(CSRF_COOKIE_DELETION_MAX_AGE_SECONDS, deletedCsrfCookie.getMaxAge());
     }
 
     private MvcResult requestCsrfCookie() throws Exception {
@@ -108,6 +124,24 @@ private MvcResult requestCsrfCookie() throws Exception {
                 .andReturn();
     }
 
+    /**
+     * Requests a CSRF cookie through the HTTPS transport path so cookie security attributes are observable.
+     */
+    private MvcResult requestSecureCsrfCookie() throws Exception {
+        return mockMvc.perform(get(CSRF_REFRESH_ENDPOINT).secure(true))
+                .andExpect(status().isOk())
+                .andReturn();
+    }
+
+    /**
+     * Verifies browser-visible attributes shared by issued and deleted CSRF cookies.
+     */
+    private static void assertBrowserReadableCsrfCookieAttributes(Cookie csrfCookie) {
+        assertEquals(CSRF_COOKIE_ROOT_PATH, csrfCookie.getPath());
+        assertEquals(CSRF_COOKIE_SAME_SITE_POLICY, csrfCookie.getAttribute(CSRF_COOKIE_SAME_SITE_ATTRIBUTE));
+        assertFalse(csrfCookie.isHttpOnly());
+    }
+
     /**
      * Exposes a harmless state-changing route so the real security filter chain can be tested.
      */

From d8f81838b0e908aa5e02f461f0e758d78d505bb8 Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:13 -0700
Subject: [PATCH 38/40] test(frontend): cover SSE failure contracts

---
 frontend/src/lib/services/sse.test.ts | 120 +++++++++++++++++++++++++-
 1 file changed, 119 insertions(+), 1 deletion(-)

diff --git a/frontend/src/lib/services/sse.test.ts b/frontend/src/lib/services/sse.test.ts
index b065609b..5299189c 100644
--- a/frontend/src/lib/services/sse.test.ts
+++ b/frontend/src/lib/services/sse.test.ts
@@ -1,9 +1,14 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { streamSse } from "./sse";
+import { streamSse, streamSseGet } from "./sse";
 
 const SSE_STREAM_RESPONSE_STATUS = 200;
+const HTTP_SERVICE_UNAVAILABLE_STATUS = 503;
 const FETCH_FAILURE_MESSAGE = "Network request failed";
 const STREAM_READ_FAILURE_MESSAGE = "Unable to read the SSE stream";
+const SERVER_EVENT_ERROR_MESSAGE = "The provider ended the stream";
+const STATUS_EVENT_MESSAGE = "Switching to an available provider";
+const STATUS_EVENT_PROVIDER = "openai";
+const MISSING_STREAM_BODY_MESSAGE = "No response body";
 
 function createSseStreamResponse(sseWireText: string): Response {
   const encoder = new TextEncoder();
@@ -63,6 +68,95 @@ describe("streamSse transport handling", () => {
     expect(onError).toHaveBeenCalledWith({ message: FETCH_FAILURE_MESSAGE });
   });
 
+  it("reports and rejects a non-abort GET fetch failure exactly once", async () => {
+    const fetchFailure = new Error(FETCH_FAILURE_MESSAGE);
+    const fetchMock = vi.fn().mockRejectedValue(fetchFailure);
+    vi.stubGlobal("fetch", fetchMock);
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(streamSseGet("/api/test/stream", { onText, onError }, "sse.test.ts")).rejects.toBe(
+      fetchFailure,
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: FETCH_FAILURE_MESSAGE });
+  });
+
+  it("reports a non-OK GET response exactly once", async () => {
+    const serviceUnavailableMessage = `HTTP ${HTTP_SERVICE_UNAVAILABLE_STATUS}: Service Unavailable`;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(null, {
+          status: HTTP_SERVICE_UNAVAILABLE_STATUS,
+          statusText: "Service Unavailable",
+        }),
+      ),
+    );
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamSseGet("/api/test/stream", { onText, onError }, "sse.test.ts"),
+    ).rejects.toThrow(serviceUnavailableMessage);
+
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: serviceUnavailableMessage });
+  });
+
+  it("reports a missing GET response body exactly once", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(null, {
+          status: SSE_STREAM_RESPONSE_STATUS,
+          statusText: "OK",
+        }),
+      ),
+    );
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamSseGet("/api/test/stream", { onText, onError }, "sse.test.ts"),
+    ).rejects.toThrow(MISSING_STREAM_BODY_MESSAGE);
+
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: MISSING_STREAM_BODY_MESSAGE });
+  });
+
+  it("reports a valid server error event exactly once", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValue(
+          createSseStreamResponse(
+            `event: error\ndata: {"message":"${SERVER_EVENT_ERROR_MESSAGE}"}\n\n`,
+          ),
+        ),
+    );
+
+    const onText = vi.fn();
+    const onError = vi.fn();
+
+    await expect(
+      streamSseGet("/api/test/stream", { onText, onError }, "sse.test.ts"),
+    ).rejects.toThrow(SERVER_EVENT_ERROR_MESSAGE);
+
+    expect(onText).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledOnce();
+    expect(onError).toHaveBeenCalledWith({ message: SERVER_EVENT_ERROR_MESSAGE });
+  });
+
   it("treats AbortError during read as a cancellation (no onError)", async () => {
     const encoder = new TextEncoder();
     const abortError = Object.assign(new Error("Aborted"), { name: "AbortError" });
@@ -141,6 +235,30 @@ describe("streamSse payload validation", () => {
     expect(onText).toHaveBeenCalledWith("Hello");
   });
 
+  it("preserves provider from a valid wire-format status event", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValue(
+          createSseStreamResponse(
+            `event: status\ndata: {"message":"${STATUS_EVENT_MESSAGE}","provider":"${STATUS_EVENT_PROVIDER}"}\n\n`,
+          ),
+        ),
+    );
+    const onText = vi.fn();
+    const onStatus = vi.fn();
+
+    await streamSse("/api/test/stream", {}, { onText, onStatus }, "sse.test.ts");
+
+    expect(onText).not.toHaveBeenCalled();
+    expect(onStatus).toHaveBeenCalledOnce();
+    expect(onStatus).toHaveBeenCalledWith({
+      message: STATUS_EVENT_MESSAGE,
+      provider: STATUS_EVENT_PROVIDER,
+    });
+  });
+
   it("rejects legacy raw text payloads", async () => {
     vi.spyOn(console, "error").mockImplementation(() => undefined);
     vi.stubGlobal(

From 46650888d7a5a59c33e4385a9e29967c8b08a6fc Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:14 -0700
Subject: [PATCH 39/40] test(frontend): preserve chat stream error identity

---
 frontend/src/lib/services/chat.test.ts | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/frontend/src/lib/services/chat.test.ts b/frontend/src/lib/services/chat.test.ts
index 881903af..327bc0af 100644
--- a/frontend/src/lib/services/chat.test.ts
+++ b/frontend/src/lib/services/chat.test.ts
@@ -16,13 +16,14 @@ describe("streamChat", () => {
   });
 
   it("surfaces a recoverable stream failure without replaying the POST", async () => {
-    const streamFailure = {
-      message: "OverflowException: malformed response frame",
+    const streamFailure = new Error("OverflowException: malformed response frame");
+    const streamError = {
+      message: streamFailure.message,
       details: "Malformed response frame at byte 512",
     };
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
-      callbacks.onError?.(streamFailure);
-      throw new Error(streamFailure.message);
+      callbacks.onError?.(streamError);
+      throw streamFailure;
     });
 
     const onChunk = vi.fn();
@@ -36,7 +37,7 @@ describe("streamChat", () => {
         onError,
         signal: streamAbortController.signal,
       }),
-    ).rejects.toThrow("OverflowException: malformed response frame");
+    ).rejects.toBe(streamFailure);
 
     expect(streamSseMock).toHaveBeenCalledTimes(1);
     expect(streamSseMock).toHaveBeenCalledWith(
@@ -52,7 +53,7 @@ describe("streamChat", () => {
     );
     expect(onStatus).not.toHaveBeenCalled();
     expect(onChunk).not.toHaveBeenCalled();
-    expect(onError).toHaveBeenCalledWith(streamFailure);
+    expect(onError).toHaveBeenCalledWith(streamError);
   });
 
   it("does not replay after a stream has emitted a chunk", async () => {

From c11049b5943ca66b7594b42aecb88999be238b3b Mon Sep 17 00:00:00 2001
From: William Callahan <william@williamcallahan.com>
Date: Mon, 13 Jul 2026 14:39:15 -0700
Subject: [PATCH 40/40] test(frontend): preserve guided stream error identity

---
 frontend/src/lib/services/guided.test.ts | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/frontend/src/lib/services/guided.test.ts b/frontend/src/lib/services/guided.test.ts
index cba8f2ae..77064d6a 100644
--- a/frontend/src/lib/services/guided.test.ts
+++ b/frontend/src/lib/services/guided.test.ts
@@ -17,13 +17,14 @@ describe("streamGuidedChat", () => {
   });
 
   it("surfaces a recoverable stream failure without replaying the POST", async () => {
-    const streamFailure = {
-      message: "OverflowException: malformed response frame",
+    const streamFailure = new Error("OverflowException: malformed response frame");
+    const streamError = {
+      message: streamFailure.message,
       details: "Malformed response frame at byte 512",
     };
     streamSseMock.mockImplementationOnce(async (_url, _body, callbacks) => {
-      callbacks.onError?.(streamFailure);
-      throw new Error(streamFailure.message);
+      callbacks.onError?.(streamError);
+      throw streamFailure;
     });
 
     const onChunk = vi.fn();
@@ -40,7 +41,7 @@ describe("streamGuidedChat", () => {
         onCitations,
         signal: streamAbortController.signal,
       }),
-    ).rejects.toThrow("OverflowException: malformed response frame");
+    ).rejects.toBe(streamFailure);
 
     expect(streamSseMock).toHaveBeenCalledTimes(1);
     expect(streamSseMock).toHaveBeenCalledWith(
@@ -57,7 +58,7 @@ describe("streamGuidedChat", () => {
     );
     expect(onStatus).not.toHaveBeenCalled();
     expect(onChunk).not.toHaveBeenCalled();
-    expect(onError).toHaveBeenCalledWith(streamFailure);
+    expect(onError).toHaveBeenCalledWith(streamError);
   });
 
   it("does not retry for non-recoverable rate-limit errors", async () => {