diff --git a/CLAUDE.md b/CLAUDE.md
index c621f83..6782c3a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -141,10 +141,25 @@ rest; a file matching no rule and no fallback **fails the build**. `aiIndex.plan
 Markdown plan (file → rule id → prompt → rough time estimate, summed per model and overall) and stops
 (no model loaded). The plan also computes each routed file's **context-window fit** up front (via
 `AiInputWindowCalculator`, the same threshold the run uses to trim): a file larger than its routed
-model's window is flagged in the plan and **always fails the build** (a hard abort). The resolution is
-**configuration only** — the plugin never auto-picks a model: the user must add a `<fieldGeneration>`
-rule with a size `<condition>` that routes oversized files to a model with a large enough context window
-(see the big-window fallback example in the POM). See `AiFieldGenerationSelector` (selection + validation), `AiCondition`/
+model's window is flagged in the plan and, **by default (`onOversize=fail`), fails the build** (a hard
+abort) — the plugin never auto-picks a model. The resolution is **configuration only**, via the rule's
+**`<onOversize>`** strategy (`AiOversizeStrategy`): `fail` (default), `sample` (trim to the window head,
+one call), `mapReduce` (chunk at line boundaries → summarize each → combine via a **hierarchical reduce**
+that batches partials to fit the window so whole-file `<maxChunks>=0` coverage isn't trimmed away;
+`<maxChunks>` bounds the time — `AiSourceChunker`; the chunk window carries a token-safety headroom so a
+token-dense chunk can't overflow the model context), or `deterministic` (model-free metadata+sample body
+— `AiDeterministicSummary`).
+So oversized files are either routed to a larger-context model or handled by a strategy; only `fail`
+entries abort. A rule may also carry an orthogonal, language-agnostic **`<facts>`** list (`AiFactCounter`
++ `AiFactExtractor`): each `{label, pattern}` reports its regex match count over the **whole** source,
+prepended to the body of **every** file the rule matches (oversize or not) — exact structural counts
+(SQL `INSERT` rows / tables / views, Java type declarations / `\bboolean\b` fields, …) that give
+downstream agents authoritative numbers the (possibly sampled) AI prose cannot reliably produce. A fact
+set can be defined once in a shared `<factDefinitions>` group and referenced from many rules by
+`<factsKey>` (`AiFactDefinition` + `AiFactDefinitionSupport`, resolved onto each rule before indexing),
+instead of repeating the `<facts>` block inline. Generation is also guarded by a **retry-on-overflow**:
+if the provider rejects a prompt as exceeding the context (the char-based trim under-counted tokens on
+dense content), the call is re-trimmed to a smaller window and retried rather than failing the build. See `AiFieldGenerationSelector` (selection + validation), `AiCondition`/
 `AiConditionEvaluator` (the tree), and `AiIndexPlan` (the rendered plan). This is how one run can index
 different file kinds/sizes with different models *and* prompts.
 
@@ -189,6 +204,15 @@ the top of `execute()`. Covered by `MojoPhaseSkipTest`.
 | `AiCondition` / `AiConditionEvaluator` | Composable and/or/not condition tree (leaves: extensions/size/lines/modifiedAfter/modifiedBefore/pathGlob) + its evaluator (`matches`/`validate`/`usesLines`) |
 | `AiIndexPlan` | The routing plan: routes grouped by model id, skips, unmatched, per-file context-window fit; renders the up-front tree |
 | `AiInputWindowCalculator` | Pure calculator for the input window (max source chars before trimming + whether a source exceeds it); single source of truth shared by the run-time trim (`AiFieldGenerationSupport`) and the plan-time over-window check (`SourceFileIndexer.classify`) |
+| `AiOversizeStrategy` | Enum of the per-rule `<onOversize>` strategies (`fail`/`sample`/`mapReduce`/`deterministic`) + case-insensitive parser; default `fail` |
+| `AiSourceChunker` | Pure line-boundary chunker for `mapReduce` (overlap + `maxChunks` representative sampling) |
+| `AiFactCounter` | Maven `@Parameter` POJO for one `<fact>` — a `{label, pattern}` deterministic counter |
+| `AiFactExtractor` | Pure: counts each `<facts>` regex over the whole source → the exact "facts" block prepended to the body (+ fail-fast pattern validation) |
+| `AiFactDefinition` | Maven `@Parameter` POJO for a named, reusable `<factDefinitions>` group `{key, facts}` |
+| `AiFactDefinitionSupport` | Key-indexed lookup: resolves each rule's `<factsKey>` to its shared group's counters (copies onto the rule) |
+| `CalibrateMojo` / `AiCalibrationRunner` | `ai-index:calibrate` goal (thin orchestration) + the indexer-layer measurer (warmup + two sized generations, prefers the binding's reported throughput, else a wall-clock differential) → `AiCalibrationMeasurement` |
+| `AiCalibration` | `<calibration>` `@Parameter` POJO on `<aiDefinition>` (`prefillTokensPerSecond`/`decodeTokensPerSecond`/`charsPerToken`); makes `AiGenerationTimeEstimator` use measured per-machine rates instead of the built-in reference-CPU model |
+| `AiDeterministicSummary` | Pure model-free body builder for `deterministic` (size, line count, head/tail sample) |
 | `AiProgressBar` | Pure ASCII progress-bar renderer (`[#####     ] 42%`); `GenerateMojo` logs it after each file, advancing by the running sum of per-file plan estimates over the grand total (with estimated time left + actual elapsed) |
 | `PackageIndexer` | Creates `package.ai.md` files with contents listings, calls AI to fill the document body |
 | `ProjectIndexer` | Phase 3: harvests each package's lead + relative link into one `project.ai.md`; deterministic listing, with an optional one-call AI `#### Overview` from the leads |
@@ -265,6 +289,7 @@ header block, so a `- F:` line in the body is never read as a link.
 | `ai-index:generate` | Phase 1: index source files and fill the AI-generated document body |
 | `ai-index:aggregate-packages` | Phase 2: aggregate package index files and fill the AI-generated document body |
 | `ai-index:aggregate-project` | Phase 3: harvest per-package leads into one `project.ai.md` (deterministic listing; optional one-call AI `#### Overview` when a `<fieldGeneration>` is configured) |
+| `ai-index:calibrate` | Preflight + per-machine timing (between `planOnly` and a real run): loads each routed model once (catches bad path / OOM / wrong native), measures prefill/decode throughput, and prints a paste-ready `<calibration>` block per `<aiDefinition>` |
 
 ### Key Parameters (`GenerateMojo`)
 
@@ -355,7 +380,7 @@ Immutable value types are implemented as Java `record` types (e.g., `AiMdDocumen
 
 | Dependency | Version | Purpose |
 |---|---|---|
-| `net.ladenthin:llama` | 5.0.3 | llama.cpp JNI binding (GGUF inference); released on Maven Central, carries the prompt-cache/slot APIs + GPU classifier jars. Brings `slf4j-api` transitively, converged to 2.0.18 via `<dependencyManagement>`. |
+| `net.ladenthin:llama` | 5.0.4 | llama.cpp JNI binding (GGUF inference); released on Maven Central, carries the prompt-cache/slot APIs + GPU classifier jars. Brings `slf4j-api` transitively, converged to 2.0.18 via `<dependencyManagement>`. |
 | `org.apache.maven:maven-plugin-api` | 3.9.13 | Maven plugin API (provided) |
 | `org.apache.maven.plugin-tools:maven-plugin-annotations` | 3.15.1 | `@Mojo`, `@Parameter` annotations (provided) |
 
diff --git a/README.md b/README.md
index d81a99c..f3e4bab 100644
--- a/README.md
+++ b/README.md
@@ -204,14 +204,40 @@ The plugin is configured from three building blocks, declared on the plugin insi
    `-DaiIndex.planOnly=true` to print the routing plan (a copy-pasteable Markdown table: file → rule id →
    prompt → context-window fit → rough time estimate, summed per model and overall) and stop before
    loading any model. The plan also checks each file against its routed model's **context window**: a
-   file too large for the window would lose content if trimmed, so the build **always fails** (a hard
-   abort). The fix is **configuration only** — the plugin never picks a model for you: add a
-   `<fieldGeneration>` rule with a size `<condition>` that routes oversized files to a model with a large
-   enough window (see the `granite-4.0-h-tiny-bigwindow` definition + the `big-window-java` / `big-window-sql` rules in the POM —
-   IBM Granite 4.0-H-Tiny, Apache-2.0, a hybrid Mamba model whose KV cache grows only linearly, configured
-   at a 384K window to cover files up to ~1 MB; verified summarizing a ~995 KB / ~268K-token file on an
-   8 GB GPU with no OOM. Quality is best within Granite's validated 128K (~500 KB) and degrades gradually
-   beyond it — a whole-file summary still beats a trimmed one).
+   file too large for the window would lose content if trimmed. What happens then is **configuration
+   only** — the plugin never picks a model for you — and is chosen per rule with `<onOversize>`:
+   - **`fail`** *(default)* — abort the build (a hard fail). The fix is to add a `<fieldGeneration>` rule
+     with a size `<condition>` that routes oversized files to a model with a large enough window (see the
+     `granite-4.0-h-tiny-bigwindow` definition + the `big-window-java` / `big-window-sql` rules in the
+     POM — IBM Granite 4.0-H-Tiny, Apache-2.0, a hybrid Mamba model whose KV cache grows only linearly,
+     configured at a 384K window to cover files up to ~1 MB; verified summarizing a ~995 KB / ~268K-token
+     file on an 8 GB GPU with no OOM).
+   - **`sample`** — feed only the head of the file (trimmed to the window) in a single call. Fast and
+     bounded; good for repetitive data where the head represents the whole.
+   - **`mapReduce`** — split the file into window-sized chunks at line boundaries (with overlap so
+     records are never torn mid-syntax), summarize each chunk, then combine the partial summaries in one
+     final call. A `<maxChunks>` cap bounds the time (a representative subset — always head + tail,
+     evenly spaced — is summarized when the file would exceed the cap), so an arbitrarily large file
+     (e.g. 7 MB) stays within a chosen per-file budget. **Route oversized files to a *small*, fast model
+     for this — not the big-window one.** Prefill is `O(n²)` in prompt length, so chunks should be small:
+     many cheap small-window passes are far faster than a few giant ones (one 384K-token pass alone can
+     dwarf a whole run). E.g. a 16K-window model with `maxChunks=6` is ~7 calls (~1 h order on a
+     reference CPU; less on GPU) and samples a representative slice — the right trade-off for repetitive
+     data. mapReduce *on* a big window is the slowest possible combination; avoid it.
+   - **`deterministic`** — no model at all: emit a deterministic body (size, line count, head/tail
+     sample). Instant; for pure data where no AI analysis is needed.
+
+   Quality from a real model is best within Granite's validated 128K (~500 KB) and degrades gradually
+   beyond it — a whole-file (or chunked) summary still beats a trimmed one.
+
+   **Exact counts with `<facts>` (optional, every file — not just oversize).** A sampled/chunked AI
+   summary can't reliably *count* things (no single call sees the whole file — it will guess "25 rows").
+   Add a `<facts>` list to a rule and each `{label, pattern}` reports its regex match count over the
+   **whole** source, prepended to the body of every file the rule matches as an exact facts line — so
+   downstream agents get authoritative structural counts in every summary. It's fully generic — the
+   meaning is in the regex, so the same mechanism counts SQL `INSERT` rows or Java `\bboolean\b` fields;
+   multi-line matching is opt-in via the inline `(?m)` flag. Keep patterns robust (a fact that miscounts
+   is worse than none). Example: `**Facts (exact, whole file):** INSERT rows: 36738; tables: 122; views: 4`.
 
 ```xml
 <plugin>
@@ -376,6 +402,18 @@ and a fallback for everything else:
       <condition><size><min>49152</min></size></condition>
     </conditions></and></condition>
   </fieldGeneration>
+  <fieldGeneration>                                  <!-- huge files: chunk over a SMALL fast window + combine -->
+    <id>java-huge</id><promptKey>file-body-java</promptKey><aiDefinitionKey>gpt-oss-20B-c16k</aiDefinitionKey>
+    <onOversize>mapReduce</onOversize><maxChunks>6</maxChunks>   <!-- ~7 cheap calls; bounds time to ~1 h/file -->
+    <facts>                                          <!-- exact whole-file counts, prepended to the body -->
+      <fact><label>boolean fields</label><pattern>\bboolean\b</pattern></fact>
+      <fact><label>methods</label><pattern>(?m)^\s+(public|private|protected).*\(</pattern></fact>
+    </facts>
+    <condition><and><conditions>
+      <condition><extensions><extension>.java</extension></extensions></condition>
+      <condition><size><min>1048576</min></size></condition>
+    </conditions></and></condition>
+  </fieldGeneration>
   <fieldGeneration>
     <id>fallback</id><fallback>true</fallback>
     <promptKey>file-body-fallback</promptKey><aiDefinitionKey>gpt-oss-20B-c96k</aiDefinitionKey>
@@ -385,7 +423,10 @@ and a fallback for everything else:
 
 Notes: size bounds are **min-exclusive / max-inclusive** so `band2.min == band1.max` is non-overlapping;
 `<lines>` works the same way; `<modifiedAfter>2026-01-01T00:00:00Z</modifiedAfter>` only (re)indexes
-recently changed files. Preview the mapping without running a model:
+recently changed files. `<onOversize>` (`fail` *(default)* / `sample` / `mapReduce` / `deterministic` —
+see the context-window note above) chooses what a rule does when a file is still larger than its routed
+model's window; `<maxChunks>` caps how many chunks `mapReduce` summarizes. Preview the mapping without
+running a model:
 
 ```
 mvn ai-index:generate -DaiIndex.planOnly=true
diff --git a/TODO.md b/TODO.md
index b48da88..645add7 100644
--- a/TODO.md
+++ b/TODO.md
@@ -15,8 +15,6 @@ recorded in git history and `crossrepostatus.md`, not here.
 
 - **Expand PIT mutation scope (optional).** `pom.xml` wires `<mutationThreshold>100</mutationThreshold>` over an explicit `<targetClasses>` list (config / document / prompt / provider / support value+logic classes, plus `indexer.AiInputWindowCalculator` and `support.AiProgressBar`), all killed at 100%. Still out (optional, need careful fixtures): `document.AiMdDocumentCodec` / `AiMdHeaderCodec`, `prompt.AiPromptPreparationSupport`, and the newer `indexer.AiIndexPlan` / `config.AiConditionGroup`. The orchestration layers (`indexer.*` walk, `mojo.*`) and the JNI provider stay out of PIT — they need a Maven/native context rather than pure-unit mutation (see crossrepostatus "Deliberate non-parity").
 
-- **Big-window fallback beyond ~1 MB.** The `granite-4.0-h-tiny-bigwindow` preset (384K context) covers source files up to ~1 MB; larger files hard-fail by design. If genuinely needed, add a still-larger preset (Granite allocates up to its 512K training limit, with further quality loss) or document a file-splitting workflow.
-
 - **Cross-repo code-quality TODOs** — see [`../workspace/policies/code-quality-todos.md`](../workspace/policies/code-quality-todos.md) for the canonical `@VisibleForTesting` design-fit review, package hierarchy review, and class/method naming review. This repo has no `@VisibleForTesting` usages today; the package and naming reviews are still open here.
 
 - **No LogCaptor smoke test needed (note, not an action).** This module has no logging code (`org.slf4j.*` not used in `src/main/java/`); production uses Maven's `Log` interface. If SLF4J logging is ever introduced, add a LogCaptor smoke test at the same time so the binding/configuration is exercised in tests.
diff --git a/pom.xml b/pom.xml
index 079ea44..850a5fb 100644
--- a/pom.xml
+++ b/pom.xml
@@ -62,7 +62,7 @@ SPDX-License-Identifier: Apache-2.0
         <!-- net.ladenthin:llama release on Maven Central. 5.0.3 carries the prompt-cache / slot APIs
              (withCachePrompt / withSlotId) used by the provider's per-file cache reuse, plus the GPU
              classifier jars (cuda13/vulkan/opencl). -->
-        <llama.version>5.0.3</llama.version>
+        <llama.version>5.0.4</llama.version>
         <!-- Native build selector for net.ladenthin:llama. Empty = the main jar (CPU, Ninja default).
              The gpu-cuda / gpu-vulkan profiles set a GPU classifier; or override with
              -Dllama.classifier=cuda13-windows-x86-64. GPU builds need their runtime on PATH
@@ -700,7 +700,7 @@ SPDX-License-Identifier: Apache-2.0
                   see ../workspace/policies/pit-mutation-testing.md.
                   Repo-specific: targetTests is the whole aiindex tree (any unit test may
                   kill a mutant); all gated classes are covered by pure-Java tests
-                  (MockAiGenerationProvider — no GGUF model needed).
+                  (MockAiGenerationProvider - no GGUF model needed).
                 -->
                 <groupId>org.pitest</groupId>
                 <artifactId>pitest-maven</artifactId>
@@ -714,6 +714,7 @@ SPDX-License-Identifier: Apache-2.0
                 <configuration>
                     <targetClasses>
                         <!-- Classes verified at 100% PIT mutation parity. Expand as more reach it. -->
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiCondition</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiConditionEvaluator</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig</param>
@@ -723,6 +724,7 @@ SPDX-License-Identifier: Apache-2.0
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiRangeCondition</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinition</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.indexer.AiCalibrationMeasurement</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.indexer.AiInputWindowCalculator</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationResult</param>
@@ -736,10 +738,17 @@ SPDX-License-Identifier: Apache-2.0
                         <param>net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.provider.AiCompletionParser</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationTimings</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProviderFactory</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.provider.MockAiGenerationProvider</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinition</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinitionSupport</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.support.AiChecksumSupport</param>
+                        <param>net.ladenthin.maven.llamacpp.aiindex.support.AiDeterministicSummary</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.support.AiGenerationTimeEstimator</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.support.AiPathSupport</param>
                         <param>net.ladenthin.maven.llamacpp.aiindex.support.AiProgressBar</param>
@@ -854,7 +863,7 @@ SPDX-License-Identifier: Apache-2.0
                             <aiDefinitions>
                                 <!--
                                   ============================================================
-                                   MODEL SELECTION GUIDE — pros / cons / when to pick each
+                                   MODEL SELECTION GUIDE - pros / cons / when to pick each
                                   ============================================================
                                   This plugin runs local GGUF models, typically CPU-only, to
                                   summarize source files (Phase 1) and packages (Phase 2). The
@@ -890,7 +899,7 @@ SPDX-License-Identifier: Apache-2.0
                                     + Purpose-built code model (FIM-aware), excellent at code structure.
                                     - 22B DENSE = heavy/slow on CPU; Q6_K variant is higher fidelity but
                                       even slower and larger (pick Q4_K for speed, Q6_K only if quality
-                                      gaps show). Non-commercial license (MNPL) — check before shipping.
+                                      gaps show). Non-commercial license (MNPL) - check before shipping.
                                     Use when: code quality matters more than speed and you have RAM.
 
                                   Qwen2.5-Coder-7B-Instruct-Q5_K_M-C16k
@@ -928,7 +937,7 @@ SPDX-License-Identifier: Apache-2.0
                                     + MoE 30B total / ~3.3B active: code-specialized AND fast on CPU; fewer
                                       active params than Gemma-4-26B-A4B; non-thinking; Apache-2.0.
                                     + Locally present (X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL.gguf,
-                                      17.7 GB); 64K context — generous but CPU-feasible (256K prefill is unusable on CPU).
+                                      17.7 GB); 64K context - generous but CPU-feasible (256K prefill is unusable on CPU).
                                     - Needs Qwen sampling (temp 0.7 / top_p 0.8 / top_k 20 / repeat 1.05).
                                     Use when: this is the go-to for most code summarization on CPU.
 
@@ -1089,7 +1098,7 @@ SPDX-License-Identifier: Apache-2.0
                                 <!-- gemma-4-26B-A4B-it-UD-Q4_K_M (32 K context)
                                      26B total / ~4B active parameters (MoE: 128 experts, 8+1 active per token).
                                      Runs at the computational cost of a ~4B dense model; quality near 27B dense.
-                                     Temperature 1.0 is critical for Gemma 4 — lowering degrades quality.
+                                     Temperature 1.0 is critical for Gemma 4 - lowering degrades quality.
                                      32k context is a practical sweet spot for code summarization on local hardware.
                                      https://huggingface.co/unsloth/gemma-4-26B-A4B-it-GGUF -->
                                 <aiDefinition>
@@ -1111,7 +1120,7 @@ SPDX-License-Identifier: Apache-2.0
                                 </aiDefinition>
                                 <!-- gemma-4-12B-it-Q4_K_M (32 K context)
                                      12B dense instruction-tuned model from Google DeepMind.
-                                     Temperature 1.0 is critical for Gemma 4 — lowering degrades quality.
+                                     Temperature 1.0 is critical for Gemma 4 - lowering degrades quality.
                                      32k context is a practical sweet spot for code summarization on local hardware.
                                      https://huggingface.co/bartowski/gemma-4-12B-it-GGUF -->
                                 <aiDefinition>
@@ -1133,7 +1142,7 @@ SPDX-License-Identifier: Apache-2.0
                                 </aiDefinition>
                                 <!-- Gemma-4-E4B-Uncensored-HauhauCS-Aggressive-Q4_K_M (32 K context)
                                      ~4B effective parameters (MoE); uncensored derivative of gemma-4-E4B-it.
-                                     Temperature 1.0 is critical for Gemma 4 — lowering degrades quality.
+                                     Temperature 1.0 is critical for Gemma 4 - lowering degrades quality.
                                      32k context is a practical sweet spot for code summarization on local hardware.
                                      https://huggingface.co/HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive -->
                                 <aiDefinition>
@@ -1157,7 +1166,7 @@ SPDX-License-Identifier: Apache-2.0
                                      Same model as Q4_K_M above; Q6_K_P is a custom lossless quantization by HauhauCS
                                      that preserves quality where it matters most (effectively 1-2 quant levels higher
                                      at only 5-15 % larger file size).
-                                     Temperature 1.0 is critical for Gemma 4 — lowering degrades quality.
+                                     Temperature 1.0 is critical for Gemma 4 - lowering degrades quality.
                                      32k context is a practical sweet spot for code summarization on local hardware.
                                      https://huggingface.co/HauhauCS/Gemma-4-E4B-Uncensored-HauhauCS-Aggressive -->
                                 <aiDefinition>
@@ -1177,7 +1186,7 @@ SPDX-License-Identifier: Apache-2.0
                                         <stopString>&lt;end_of_turn&gt;</stopString>
                                     </stopStrings>
                                 </aiDefinition>
-                                <!-- Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL (64 K context) — the
+                                <!-- Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL (64 K context) - the
                                      locally-present file and the active model for BOTH AI phases
                                      (file-body + package-body). MoE 30B total / ~3.3B active,
                                      non-thinking (emits no <think> blocks, so no enable_thinking flag
@@ -1187,7 +1196,7 @@ SPDX-License-Identifier: Apache-2.0
                                      Official Qwen3-Coder sampling (model card): temperature 0.7,
                                      top_p 0.8, top_k 20, repetition_penalty 1.05.
                                      Context: native window is 262144; 64 K is a deliberate, generous
-                                     yet CPU-feasible cap — 256 K prefill is unusable on CPU.
+                                     yet CPU-feasible cap - 256 K prefill is unusable on CPU.
                                      maxOutputTokens is deliberately 1536 (NOT the model card's generic
                                      65536): the purpose here is short, dense bullet-point summaries,
                                      not long code generations, so a tight output cap keeps each
@@ -1231,7 +1240,7 @@ SPDX-License-Identifier: Apache-2.0
                                     <repeatPenalty>1.05</repeatPenalty>
                                 </aiDefinition>
                                 <!-- Qwen3-4B-Instruct-2507-Q5_K_M (32 K context)
-                                     Dense 4B, Apache-2.0, NON-thinking instruct variant (no &lt;think&gt; blocks) —
+                                     Dense 4B, Apache-2.0, NON-thinking instruct variant (no &lt;think&gt; blocks) -
                                      the fast/low-RAM tier for short structured summaries on a laptop.
                                      Single-file GGUF (2.89 GB). Download:
                                      https://huggingface.co/unsloth/Qwen3-4B-Instruct-2507-GGUF/resolve/main/Qwen3-4B-Instruct-2507-Q5_K_M.gguf -->
@@ -1314,10 +1323,10 @@ SPDX-License-Identifier: Apache-2.0
                                     <repeatPenalty>1.05</repeatPenalty>
                                 </aiDefinition>
                                 <!-- ============================================================
-                                     gpt-oss-20B — three ready-to-use presets, tiered by the LARGEST
+                                     gpt-oss-20B - three ready-to-use presets, tiered by the LARGEST
                                      source file you need to cover. All use reasoningEffort=low: the
-                                     benchmark (docs/ai-index-benchmark/COMPARISON.md §11) shows low is
-                                     best for dense code summaries — fastest, and the whole output
+                                     benchmark (docs/ai-index-benchmark/COMPARISON.md section 11) shows low is
+                                     best for dense code summaries - fastest, and the whole output
                                      budget goes to the summary instead of in-band reasoning. Raise the
                                      effort only for genuinely reasoning-heavy generation AND raise
                                      maxOutputTokens with it, or the final answer is truncated.
@@ -1326,8 +1335,8 @@ SPDX-License-Identifier: Apache-2.0
                                      (set via the ai.model property; the c16k/c48k/c96k presets are the
                                      same model family at narrower windows.)
                                      Why the widest practical window is the default: a measured A/B
-                                     (§11) proved that a larger contextSize costs ONLY KV RAM, NOT
-                                     per-file time — for the same small file, 16K vs 96K had identical
+                                     (section 11) proved that a larger contextSize costs ONLY KV RAM, NOT
+                                     per-file time - for the same small file, 16K vs 96K had identical
                                      prefill/decode/wall time; only RAM grew (~+400 MiB per +16K). So
                                      defaulting to 96K means one preset covers EVERY file up to ~250 KB
                                      with no trimming and no truncation, while small files stay just as
@@ -1358,7 +1367,7 @@ SPDX-License-Identifier: Apache-2.0
                                      Hard ceiling: the 128K window caps input at ~480-500 KB of code, but
                                      CPU prefill+decode time and KV RAM make ~250 KB the practical limit.
                                      Prefill is the dominant cost on big files (O(n^2)), not the effort
-                                     level — see the estimate the plugin logs per file.
+                                     level - see the estimate the plugin logs per file.
                                      ============================================================ -->
                                 <aiDefinition>
                                     <key>gpt-oss-20B-c16k</key>
@@ -1560,9 +1569,11 @@ SPDX-License-Identifier: Apache-2.0
                                      window at run time); the cpt-3 check admits up to ~1.16 MB. reasoningEffort
                                      is empty: Granite has no gpt-oss harmony channels, so no reasoning kwarg is
                                      sent. The size-routing rules that target this key live in the ai-generate
-                                     <fieldGenerations> below (ids big-window-java and big-window-sql). For >~1 MB files, split them or
-                                     add a still-larger preset (Granite allocates up to its 512K training limit
-                                     here, with further quality loss). -->
+                                     <fieldGenerations> below (ids big-window-java and big-window-sql), for the
+                                     ~275 KB .. ~1 MB band (one pass). Files > ~1 MB are NOT summarized in one
+                                     giant pass here (O(n^2) prefill makes that far too slow); they route to the
+                                     small-window granite-4.0-h-1b-fastchunk preset via the huge-java/huge-sql
+                                     rules and are map-reduced (cheap small chunks, maxChunks-bounded). -->
                                 <aiDefinition>
                                     <key>granite-4.0-h-tiny-bigwindow</key>
                                     <modelPath>X:/Modelle/granite-4.0-h-tiny-Q4_K_M.gguf</modelPath>
@@ -1582,6 +1593,43 @@ SPDX-License-Identifier: Apache-2.0
                                     <reasoningEffort></reasoningEffort>
                                 </aiDefinition>
 
+                                <!-- Small/fast window for the map-reduce of VERY large files (multi-MB data),
+                                     the default fallback for oversized sources. Uses the SMALLEST Granite 4.0
+                                     hybrid (H-1B, ~1.5B, Apache-2.0, IBM) at a SMALL 16K window on purpose.
+                                     Rationale: prefill cost is O(n^2) in prompt length, so one big 384K pass is
+                                     far slower than many small 16K passes; and a tiny 1.5B model roughly doubles
+                                     CPU throughput vs the 7B/3B siblings. Chunking at ~48 KB (16K*cpt3 minus the
+                                     prompt) and capping <maxChunks> keeps a file of ANY size to a handful of cheap
+                                     calls, sampling a representative head/tail/spread - the right trade-off for
+                                     repetitive data where no precise whole-file read is needed.
+
+                                     MEASURED on this machine (CPU-only, 16 threads, Q4_K_M): ~175 tok/s prefill,
+                                     ~85 s per full 16K chunk, so a maxChunks=6 run is ~8.5 min PER FILE regardless
+                                     of file size (1 MB or 1 GB - you sample 6 windows). On GPU the same run is
+                                     ~40 s. H-1B loads on the existing llama 5.0.3 native (granitehybrid arch, no
+                                     rebuild). Note: reading EVERY byte of a GB-scale file is not minutes on any
+                                     CPU (~135 h at this rate); raise <maxChunks> to read more (~85 s/chunk added)
+                                     or use onOversize=deterministic/sample for the repetitive bulk. Routed via the
+                                     huge-java / huge-sql rules below (priority above big-window). -->
+                                <aiDefinition>
+                                    <key>granite-4.0-h-1b-fastchunk</key>
+                                    <modelPath>X:/Modelle/granite-4.0-h-1b-Q4_K_M.gguf</modelPath>
+                                    <contextSize>16384</contextSize>
+                                    <gpuLayers>${ai.gpuLayers}</gpuLayers>
+                                    <mainGpu>${ai.mainGpu}</mainGpu>
+                                    <devices>${ai.devices}</devices>
+                                    <maxOutputTokens>1536</maxOutputTokens>
+                                    <temperature>0.2</temperature>
+                                    <threads>8</threads>
+                                    <charsPerToken>3</charsPerToken>
+                                    <warnOnTrim>true</warnOnTrim>
+                                    <topP>1.0</topP>
+                                    <topK>0</topK>
+                                    <minP>0.05</minP>
+                                    <repeatPenalty>1.0</repeatPenalty>
+                                    <reasoningEffort></reasoningEffort>
+                                </aiDefinition>
+
                                 <aiDefinition>
                                     <key>EXP-Qwen3-Coder-30B</key>
                                     <modelPath>X:/Modelle/Qwen3-Coder-30B-A3B-Instruct-UD-Q4_K_XL.gguf</modelPath>
@@ -1596,7 +1644,7 @@ SPDX-License-Identifier: Apache-2.0
                                     <repeatPenalty>1.05</repeatPenalty>
                                 </aiDefinition>
                                 <!-- ============================================================
-                                     EXPERIMENT MODELS — batch 2 (claude2026_06_26_00)
+                                     EXPERIMENT MODELS - batch 2 (claude2026_06_26_00)
                                      New shortlist candidates, all context 16384. Recommended
                                      sampling per each model card.
                                      ============================================================ -->
@@ -1665,7 +1713,7 @@ SPDX-License-Identifier: Apache-2.0
 You are a Java code indexer. Produce a dense, structured markdown summary of ONE Java source file for a searchable code index. Prioritize core logic, types, and data flow. Avoid filler words. Write in English.
 
 ## Output: start with the lead, then the sections below.
-Begin with a single blockquote line — one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what it accomplishes), not how it is named or structured. Prefer the words a human would search ("Calculates VAT for invoices") over class mechanics ("Service class with three methods"):
+Begin with a single blockquote line - one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what it accomplishes), not how it is named or structured. Prefer the words a human would search ("Calculates VAT for invoices") over class mechanics ("Service class with three methods"):
 > <one-sentence domain essence>
 
 Then output these sections as markdown. Omit any section that does not apply. Use '####' for section labels. Never use '###' or higher.
@@ -1717,7 +1765,7 @@ line, then a blank line, then the source. Index only what is literally present t
 You are a SQL schema indexer. Produce a dense, structured markdown summary of ONE SQL source file (DDL/DML: tables, views, procedures, functions, triggers) for a searchable code index. Prioritize the schema shape, the tables read vs written, columns, and relationships. Avoid filler words. Write in English.
 
 ## Output: start with the lead, then the sections below.
-Begin with a single blockquote line — one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what data it models or what operation it performs), not how it is named:
+Begin with a single blockquote line - one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what data it models or what operation it performs), not how it is named:
 > <one-sentence domain essence>
 
 Then output these sections as markdown. Omit any section that does not apply. Use '####' for section labels. Never use '###' or higher.
@@ -1765,7 +1813,7 @@ line, then a blank line, then the source. Index only what is literally present t
 You are a multi-language code indexer. Produce a dense, structured markdown summary of ONE source file (Java, C/C++, OpenCL, SQL, or similar) for a searchable code index. Prioritize core logic and data flow. Avoid filler words. Write in English.
 
 ## Output: start with the lead, then the sections below.
-Begin with a single blockquote line — one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what it accomplishes), not how it is named or structured. Prefer the words a human would search ("Calculates VAT for invoices") over class mechanics ("Service class with three methods"):
+Begin with a single blockquote line - one sentence capturing what this file does in DOMAIN terms: the business/functional purpose a developer would search for (what it accomplishes), not how it is named or structured. Prefer the words a human would search ("Calculates VAT for invoices") over class mechanics ("Service class with three methods"):
 > <one-sentence domain essence>
 
 Then output these sections as markdown. Omit any section that does not apply. Use '####' for section labels. Never use '###' or higher.
@@ -1810,10 +1858,10 @@ line, then a blank line, then the source. Index only what is literally present t
                                 <promptDefinition>
                                     <key>package-body</key>
                                     <template><![CDATA[
-You are a multi-language code indexer. You receive the already-generated per-file summaries of all files in ONE package or directory (NOT raw source code). Produce one dense, structured markdown summary of the whole package for a searchable code index. Synthesize and group — do not just concatenate the file summaries. Avoid filler. Write in English.
+You are a multi-language code indexer. You receive the already-generated per-file summaries of all files in ONE package or directory (NOT raw source code). Produce one dense, structured markdown summary of the whole package for a searchable code index. Synthesize and group - do not just concatenate the file summaries. Avoid filler. Write in English.
 
 ## Output: start with the lead, then the sections below.
-Begin with a single blockquote line — one sentence capturing what this package does as a whole in DOMAIN terms: the business/functional responsibility a developer would search for, not how it is named or layered:
+Begin with a single blockquote line - one sentence capturing what this package does as a whole in DOMAIN terms: the business/functional responsibility a developer would search for, not how it is named or layered:
 > <one-sentence domain essence>
 
 Then output these sections as markdown. Omit any that do not apply. Use '####' for labels. Never '###' or higher.
@@ -1857,7 +1905,7 @@ You are writing a short overview for the very top of a project's code index. You
 per-package one-line leads (already generated, one sentence per package). Synthesize them: name the main
 subsystems and how they fit together, in 2 to 4 sentences. Use domain terms a developer would search for.
 No headings, no bullet lists, no code fences, no XML tags, no formatter comments. Write in English. Base
-every statement only on the provided leads — never invent packages or behavior not present in them.
+every statement only on the provided leads - never invent packages or behavior not present in them.
 
 The index file path and the per-package one-line leads are provided in the next (user) message:
 the path on the first line, then a blank line, then the leads to synthesize.
@@ -1875,10 +1923,10 @@ the path on the first line, then a blank line, then the leads to synthesize.
 You are a Java code indexer. Produce a dense, structured markdown summary of ONE Java source file for a searchable code index read by AI agents. Prioritize core logic, types, and data flow. Be terse. Write in English.
 
 ## Output
-Begin with a single blockquote line — one sentence capturing what this file does in DOMAIN terms (the searchable business/functional purpose, not class mechanics):
+Begin with a single blockquote line - one sentence capturing what this file does in DOMAIN terms (the searchable business/functional purpose, not class mechanics):
 > <one-sentence domain essence>
 
-Then output ONLY the sections below that carry real information. OMIT any section that would be empty, "none", or "not applicable" — do not emit a heading just to say nothing. Use '####' for section labels, never '###' or higher.
+Then output ONLY the sections below that carry real information. OMIT any section that would be empty, "none", or "not applicable" - do not emit a heading just to say nothing. Use '####' for section labels, never '###' or higher.
 
 TRIVIAL-FILE RULE: if the unit has no public behavior to describe (e.g. a marker/annotation, an enum that only lists constants, or a near-empty type), output ONLY the blockquote lead and a single '#### Purpose' line, and stop.
 
@@ -1898,7 +1946,7 @@ What comes out: return types, produced/mutated state, written resources, side ef
 The essential steps/algorithm/responsibility as bullets. The most important section.
 
 #### Public API
-Each public/protected member as `name(params) -> returnType` + a <=6-word purpose clause. EXCEPTION: for plain data/config classes that are only getters/setters (e.g. Lombok beans), DO NOT list each accessor — write one line: "JavaBean getters/setters for: <comma-separated field names>".
+Each public/protected member as `name(params) -> returnType` + a <=6-word purpose clause. EXCEPTION: for plain data/config classes that are only getters/setters (e.g. Lombok beans), DO NOT list each accessor - write one line: "JavaBean getters/setters for: <comma-separated field names>".
 
 #### Dependencies
 Referenced types as searchable names. EXCLUDE this file's own type and java.lang.* .
@@ -1907,7 +1955,7 @@ Referenced types as searchable names. EXCLUDE this file's own type and java.lang
 Notable thrown/caught exceptions, null-handling, error conditions.
 
 #### Concurrency
-Threading, immutability, or thread-safety notes — only if the source actually shows them.
+Threading, immutability, or thread-safety notes - only if the source actually shows them.
 
 ## Rules
 - Markdown bullets and short clauses, not prose paragraphs.
@@ -1926,13 +1974,13 @@ line, then a blank line, then the source. Index only what is literally present t
                                 <promptDefinition>
                                     <key>package-body-v2</key>
                                     <template><![CDATA[
-You are a multi-language code indexer. You receive the already-generated per-file summaries of all files in ONE package or directory (NOT raw source). Produce one dense, structured markdown summary of the whole package for a searchable code index read by AI agents. Synthesize and group — do not concatenate. Be terse. Write in English.
+You are a multi-language code indexer. You receive the already-generated per-file summaries of all files in ONE package or directory (NOT raw source). Produce one dense, structured markdown summary of the whole package for a searchable code index read by AI agents. Synthesize and group - do not concatenate. Be terse. Write in English.
 
 ## Output
-Begin with a single blockquote line — one sentence capturing what this package does as a whole in DOMAIN terms:
+Begin with a single blockquote line - one sentence capturing what this package does as a whole in DOMAIN terms:
 > <one-sentence domain essence>
 
-SINGLE-CHILD RULE: if the input describes only ONE child package/file and no other content, output ONLY the blockquote lead restating that child's responsibility, and stop — emit no sections.
+SINGLE-CHILD RULE: if the input describes only ONE child package/file and no other content, output ONLY the blockquote lead restating that child's responsibility, and stop - emit no sections.
 
 Otherwise output ONLY the sections below that carry real information. OMIT any that would be empty. Use '####' for labels, never '###' or higher.
 
@@ -2023,26 +2071,128 @@ message: the path on the first line, then a blank line, then the summaries to sy
                                         <fileExtension>.java</fileExtension>
                                         <fileExtension>.sql</fileExtension>
                                     </fileExtensions>
+                                    <!--
+                                        Reusable fact-counter groups. Each <fact> reports its regex match count
+                                        over the WHOLE source (exact, language-agnostic structural counts the
+                                        sampled AI prose cannot reliably produce). Defined ONCE here and referenced
+                                        from rules below via <factsKey>, instead of repeating the same <facts>
+                                        block inline on the normal + huge rule for each language. Keep patterns
+                                        robust (line-anchored / unambiguous) - a fact that miscounts is worse than
+                                        none. (?m) opts into multi-line matching; (?i) case-insensitive for SQL.
+                                    -->
+                                    <factDefinitions>
+                                        <factDefinition>
+                                            <key>java-facts</key>
+                                            <facts>
+                                                <fact><label>type declarations</label><pattern>(?m)^\s*(?:public\s+|final\s+|abstract\s+|sealed\s+|non-sealed\s+|static\s+)*(?:class|interface|enum|record)\s+\w</pattern></fact>
+                                                <fact><label>public declarations</label><pattern>\bpublic\b</pattern></fact>
+                                                <fact><label>TODO/FIXME</label><pattern>\b(?:TODO|FIXME)\b</pattern></fact>
+                                                <fact><label>@Override</label><pattern>@Override\b</pattern></fact>
+                                                <!-- Structural counts validated against real OpenJDK source (see
+                                                     JavaStructureFactPatternsTest). These are regex heuristics, so the labels are
+                                                     honest: methods are "(approx)" (~3%, includes constructors - subtract them),
+                                                     and the field count only sees fields with a STRONG modifier (final-only and
+                                                     package-private fields are deliberately NOT counted, to avoid counting final
+                                                     local variables). For exact structure you would need a real Java parser. -->
+                                                <fact><label>methods (approx)</label><pattern>(?m)^[ \t]*(?:(?:public|private|protected|static|final|abstract|default|synchronized|native|strictfp)[ \t]+)*(?:&lt;[^>]+>[ \t]*)?(?!(?:if|for|while|switch|catch|return|new|else|do|try|synchronized|assert|throw)\b)[A-Za-z_$][\w$.]*(?:&lt;[^;{}=]*>)?(?:\[\])*[ \t]+([A-Za-z_$]\w*)[ \t]*\([^;{]*\)(?:[ \t]*throws[ \t][\w$., \t]+)?[ \t]*[{;]</pattern></fact>
+                                                <fact><label>constructors</label><pattern>(?m)^[ \t]*(?:(?:public|private|protected)[ \t]+)?([A-Z][A-Za-z0-9_$]*)[ \t]*\([^;{]*\)(?:[ \t]*throws[ \t][\w$., \t]+)?[ \t]*\{</pattern></fact>
+                                                <fact><label>field declarations (w/ modifier)</label><pattern>(?m)^[ \t]*(?:(?:public|private|protected|static|transient|volatile|final)[ \t]+)*(?:public|private|protected|static|transient|volatile)[ \t]+(?:(?:public|private|protected|static|transient|volatile|final)[ \t]+)*(?!class\b|interface\b|enum\b|record\b|void\b|new\b)[A-Za-z_$][\w$.]*(?:&lt;[^;{}=]*>)?(?:\[\])*[ \t]+([A-Za-z_$]\w*(?:[ \t]*,[ \t]*[A-Za-z_$]\w*)*)[ \t]*(?:=[^;]*)?;</pattern></fact>
+                                            </facts>
+                                        </factDefinition>
+                                        <factDefinition>
+                                            <key>sql-facts</key>
+                                            <facts>
+                                                <fact><label>INSERT rows</label><pattern>(?im)^\s*INSERT\s+INTO\b</pattern></fact>
+                                                <fact><label>tables</label><pattern>(?im)^\s*CREATE\s+TABLE\b</pattern></fact>
+                                                <fact><label>views</label><pattern>(?im)^\s*CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\b</pattern></fact>
+                                                <fact><label>indexes</label><pattern>(?im)^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\b</pattern></fact>
+                                                <fact><label>functions/procedures</label><pattern>(?im)^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\b</pattern></fact>
+                                            </facts>
+                                        </factDefinition>
+                                    </factDefinitions>
                                     <fieldGenerations>
-                                        <!-- Big-window fallback rules: a source larger than the default
-                                             model's window (~275 KB at 96K/charsPerToken 3) would be trimmed,
-                                             so route it to the large-context granite-4.0-h-tiny-bigwindow
-                                             model instead (Granite's 384K window covers up to ~1 MB; the
-                                             cpt-3 window check admits up to ~1.16 MB). There is one big-window
-                                             rule per source kind so each keeps its own prompt: big-window-java
-                                             (file-body-java) and big-window-sql (file-body-sql). Each has higher
-                                             priority than its plain java/sql counterpart so it wins for oversized
-                                             files; normal-sized files never match (size min) and fall through to
-                                             the plain rule. Without rules like these, a file larger than the
-                                             default model's window hard-fails the build (the plugin never
-                                             auto-selects a model) - this is how YOU satisfy that check. Threshold
-                                             is conservative; tune to your model's window. (A file beyond Granite's
-                                             window fails too: split it or add a still-larger fallback.) -->
+                                        <!-- Size-tiered routing for large files. THREE bands per source kind, by
+                                             ascending priority so the most specific (largest) wins:
+
+                                               plain java/sql (no priority)  files up to ~275 KB  -> ${ai.model}, one pass
+                                               big-window-*   (priority 100) ~275 KB .. ~1 MB     -> granite bigwindow, ONE 384K pass
+                                               huge-*         (priority 200) > ~1 MB              -> granite fastchunk, mapReduce
+
+                                             Why a separate huge band instead of just map-reducing on the big window?
+                                             Prefill is O(n^2) in prompt length, so ONE big 384K pass over a multi-MB file
+                                             is catastrophically slow, and map-reducing AT the big window (6 x 384K passes)
+                                             is worse still. The fast path is the opposite: chunk with a SMALL window
+                                             (granite-4.0-h-1b-fastchunk, 16K) so each prefill is cheap, and cap
+                                             <maxChunks> so a 7 MB file stays a handful of calls (~1 h order on the
+                                             reference CPU; less on GPU) - sampling a representative head/tail/spread, which
+                                             is the right trade-off for repetitive data needing no precise whole-file read.
+
+                                             Each band has its own prompt (file-body-java / file-body-sql). Without the
+                                             big-window/huge rules a file larger than ${ai.model}'s window hard-fails the
+                                             build (the plugin never auto-selects a model) - these rules are how YOU satisfy
+                                             that check. Default onOversize=fail still aborts any rule that does not opt into
+                                             sample/mapReduce/deterministic. Thresholds are conservative; tune to your models. -->
+                                        <fieldGeneration>
+                                            <id>huge-java</id>
+                                            <promptKey>file-body-java</promptKey>
+                                            <aiDefinitionKey>granite-4.0-h-1b-fastchunk</aiDefinitionKey>
+                                            <priority>200</priority>
+                                            <!-- Map-reduce on a SMALL fast window: chunk at line boundaries, summarize each,
+                                                 then combine. maxChunks bounds the run time to ~60-90 min/file by sampling a
+                                                 representative subset (head + tail + evenly spaced). Alternatives for pure
+                                                 data: sample (head only, one call) or deterministic (no model, instant). -->
+                                            <onOversize>mapReduce</onOversize>
+                                            <maxChunks>6</maxChunks>
+                                            <factsKey>java-facts</factsKey>
+                                            <condition>
+                                                <and>
+                                                    <conditions>
+                                                        <condition>
+                                                            <extensions><extension>.java</extension></extensions>
+                                                        </condition>
+                                                        <condition>
+                                                            <size><min>1000000</min></size>
+                                                        </condition>
+                                                    </conditions>
+                                                </and>
+                                            </condition>
+                                        </fieldGeneration>
+                                        <fieldGeneration>
+                                            <id>huge-sql</id>
+                                            <promptKey>file-body-sql</promptKey>
+                                            <aiDefinitionKey>granite-4.0-h-1b-fastchunk</aiDefinitionKey>
+                                            <priority>200</priority>
+                                            <onOversize>mapReduce</onOversize>
+                                            <maxChunks>6</maxChunks>
+                                            <!-- Deterministic, EXACT whole-file counts prepended to the AI body. The
+                                                 sampled map-reduce prose can't count reliably (no call sees the whole
+                                                 file), so each <fact> reports its regex match count over the FULL
+                                                 source. Fully generic/language-agnostic - the meaning is in the regex,
+                                                 so the same mechanism counts INSERT rows here or `\bboolean\b` fields
+                                                 in Java. Multi-line matching is opt-in via the inline (?m) flag. -->
+                                            <factsKey>sql-facts</factsKey>
+                                            <condition>
+                                                <and>
+                                                    <conditions>
+                                                        <condition>
+                                                            <extensions><extension>.sql</extension></extensions>
+                                                        </condition>
+                                                        <condition>
+                                                            <size><min>1000000</min></size>
+                                                        </condition>
+                                                    </conditions>
+                                                </and>
+                                            </condition>
+                                        </fieldGeneration>
                                         <fieldGeneration>
                                             <id>big-window-java</id>
                                             <promptKey>file-body-java</promptKey>
                                             <aiDefinitionKey>granite-4.0-h-tiny-bigwindow</aiDefinitionKey>
                                             <priority>100</priority>
+                                            <!-- ~275 KB .. ~1 MB: fits Granite's 384K window, summarized in ONE pass
+                                                 (fast on GPU). Files > ~1 MB are caught by huge-java above (priority 200),
+                                                 so this rule never needs to handle the oversize case; default
+                                                 onOversize=fail is the safe floor if the huge rule is removed. -->
                                             <condition>
                                                 <and>
                                                     <conditions>
@@ -2078,6 +2228,11 @@ message: the path on the first line, then a blank line, then the summaries to sy
                                             <id>java</id>
                                             <promptKey>file-body-java</promptKey>
                                             <aiDefinitionKey>${ai.model}</aiDefinitionKey>
+                                            <!-- Exact, whole-file structural counts prepended to EVERY Java summary (not just
+                                                 oversize files), giving downstream agents authoritative numbers the prose need
+                                                 not restate. Shared, defined once in <factDefinitions> above and referenced by
+                                                 key here (and by huge-java) instead of repeating the block inline. -->
+                                            <factsKey>java-facts</factsKey>
                                             <condition>
                                                 <extensions><extension>.java</extension></extensions>
                                             </condition>
@@ -2086,6 +2241,7 @@ message: the path on the first line, then a blank line, then the summaries to sy
                                             <id>sql</id>
                                             <promptKey>file-body-sql</promptKey>
                                             <aiDefinitionKey>${ai.model}</aiDefinitionKey>
+                                            <factsKey>sql-facts</factsKey>
                                             <condition>
                                                 <extensions><extension>.sql</extension></extensions>
                                             </condition>
@@ -2120,7 +2276,7 @@ message: the path on the first line, then a blank line, then the summaries to sy
                             </execution>
 
                             <!--
-                                Phase 3 — project index. Harvests the per-package lead already produced by
+                                Phase 3 - project index. Harvests the per-package lead already produced by
                                 aggregate-packages into a single project.ai.md. Bound to prepare-package so it
                                 runs after process-resources (aggregate-packages).
 
diff --git a/spotbugs-exclude.xml b/spotbugs-exclude.xml
index 1961980..986f75c 100644
--- a/spotbugs-exclude.xml
+++ b/spotbugs-exclude.xml
@@ -84,6 +84,7 @@ SPDX-License-Identifier: Apache-2.0
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.GenerateMojo"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.AggregatePackagesMojo"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.AggregateProjectMojo"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.CalibrateMojo"/>
         </Or>
         <Bug pattern="SPP_FIELD_COULD_BE_STATIC"/>
     </Match>
@@ -116,6 +117,7 @@ SPDX-License-Identifier: Apache-2.0
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.AbstractAiIndexMojo"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.AggregatePackagesMojo"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.GenerateMojo"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.CalibrateMojo"/>
         </Or>
         <Bug pattern="IMC_IMMATURE_CLASS_NO_EQUALS"/>
     </Match>
@@ -313,6 +315,81 @@ SPDX-License-Identifier: Apache-2.0
         <Bug pattern="OPM_OVERLY_PERMISSIVE_METHOD"/>
     </Match>
 
+    <!--
+        THROWS_METHOD_THROWS_RUNTIMEEXCEPTION on AiFieldGenerationSupport.generateWithOverflowRetry.
+        fb-contrib flags the `throw e` as a method throwing a RuntimeException, but this is not raising a
+        new unchecked exception as control flow - it RE-THROWS the provider's own caught exception to
+        propagate it unchanged (the retry loop only intercepts a context-overflow, identified by message,
+        and otherwise gives up by rethrowing). The provider (JNI binding) throws an unchecked
+        LlamaException; catching a more specific type would couple the indexer to the binding, which the
+        message-based detection deliberately avoids. Scoped to the one retry method.
+    -->
+    <Match>
+        <Class name="net.ladenthin.maven.llamacpp.aiindex.indexer.AiFieldGenerationSupport"/>
+        <Method name="generateWithOverflowRetry"/>
+        <Bug pattern="THROWS_METHOD_THROWS_RUNTIMEEXCEPTION"/>
+    </Match>
+
+    <!--
+        RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE on LlamaCppJniAiGenerationProvider.generateWithTimings.
+        ChatResponse.getTimings() is unannotated in the binding (not @NullMarked), so the checker treats it
+        as non-null and flags the defensive null-guard as redundant. The guard is intentional: a build or
+        response without a "timings" object must degrade to zero rates (letting the caller's wall-clock
+        fallback act), not NPE. Scoped to the one method.
+    -->
+    <Match>
+        <Class name="net.ladenthin.maven.llamacpp.aiindex.provider.LlamaCppJniAiGenerationProvider"/>
+        <Method name="generateWithTimings"/>
+        <Bug pattern="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE"/>
+    </Match>
+
+    <!--
+        OPM_OVERLY_PERMISSIVE_METHOD on AiFactDefinitionSupport.facts. fb-contrib flags the public facts(key)
+        as "could be more restrictive" from bytecode shape (it is called from resolveFactsKeys in the same
+        class), but it is the class's public lookup API and is exercised directly by unit tests. Same
+        rationale as the AiGenerationTimeEstimator / AiProgressBar OPM suppressions.
+    -->
+    <Match>
+        <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinitionSupport"/>
+        <Bug pattern="OPM_OVERLY_PERMISSIVE_METHOD"/>
+    </Match>
+
+    <!--
+        DCN_NULLPOINTER_EXCEPTION on GenerateMojo.resolveSharedFacts. Same deliberate translation bridge as
+        AbstractAiIndexMojo.buildPromptSupport (see that suppression's rationale): AiFactDefinitionSupport's
+        Objects.requireNonNull validation throws NPE by Java convention on a null definition key, which this
+        method catches and rethrows as a Maven MojoExecutionException (a user configuration error) rather
+        than a plugin bug. Scoped to the one method.
+    -->
+    <Match>
+        <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.GenerateMojo"/>
+        <Method name="resolveSharedFacts"/>
+        <Bug pattern="DCN_NULLPOINTER_EXCEPTION"/>
+    </Match>
+
+    <!--
+        EI_EXPOSE_REP / EI_EXPOSE_REP2 on the <calibration> accessors of the Maven @Parameter config beans
+        (AiModelDefinition, AiGenerationConfig). Same rationale as the routing-config EI suppression above:
+        these are mutable JavaBeans the plugin framework populates via reflection; the AiCalibration the
+        getter returns / the setter stores IS the configuration, read once during the run and never shared
+        across threads. A defensive copy would deep-clone an immutable-after-injection value for no gain.
+    -->
+    <Match>
+        <Or>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinition"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig"/>
+        </Or>
+        <Or>
+            <Method name="getCalibration"/>
+            <Method name="setCalibration"/>
+        </Or>
+        <Or>
+            <Bug pattern="EI_EXPOSE_REP"/>
+            <Bug pattern="EI_EXPOSE_REP2"/>
+        </Or>
+    </Match>
+
+
     <!--
         EI_EXPOSE_REP / EI_EXPOSE_REP2 on the rule-routing config beans and the routing-plan model.
 
@@ -336,6 +413,7 @@ SPDX-License-Identifier: Apache-2.0
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiCondition"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiConditionGroup"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinition"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.indexer.AiIndexPlan"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.indexer.AiIndexPlan$Entry"/>
         </Or>
@@ -360,6 +438,8 @@ SPDX-License-Identifier: Apache-2.0
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiConditionGroup"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiRangeCondition"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFileContext"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinition"/>
         </Or>
         <Bug pattern="IMC_IMMATURE_CLASS_NO_EQUALS"/>
     </Match>
@@ -413,14 +493,17 @@ SPDX-License-Identifier: Apache-2.0
         <Or>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiConditionEvaluator"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationSelector"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.indexer.AiIndexPlan"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.support.AiGenerationTimeEstimator"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.AbstractAiIndexMojo"/>
             <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.GenerateMojo"/>
+            <Class name="net.ladenthin.maven.llamacpp.aiindex.mojo.CalibrateMojo"/>
         </Or>
         <Or>
             <Bug pattern="CE_CLASS_ENVY"/>
             <Bug pattern="OCP_OVERLY_CONCRETE_PARAMETER"/>
+            <Bug pattern="OCP_OVERLY_CONCRETE_COLLECTION_PARAMETER"/>
             <Bug pattern="OPM_OVERLY_PERMISSIVE_METHOD"/>
             <Bug pattern="UCPM_USE_CHARACTER_PARAMETERIZED_METHOD"/>
             <Bug pattern="WEM_WEAK_EXCEPTION_MESSAGING"/>
@@ -428,4 +511,18 @@ SPDX-License-Identifier: Apache-2.0
         </Or>
     </Match>
 
+    <!--
+        IMPROPER_UNICODE on AiOversizeStrategy.fromConfig. The findsecbugs detector flags any
+        case-insensitive comparison (equalsIgnoreCase, and likewise toLowerCase/toUpperCase) because
+        Unicode case folding can change string length for some scripts. Here the compared values are a
+        fixed, closed set of ASCII config tokens (fail/sample/mapReduce/deterministic) authored by the
+        operator in POM XML, not user/locale text; matching a configured &lt;onOversize&gt; value
+        case-insensitively is the intended, safe behaviour. Scoped to the one parsing method.
+    -->
+    <Match>
+        <Class name="net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy"/>
+        <Method name="fromConfig"/>
+        <Bug pattern="IMPROPER_UNICODE"/>
+    </Match>
+
 </FindBugsFilter>
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java
new file mode 100644
index 0000000..5e49ea2
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibration.java
@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import lombok.ToString;
+
+/**
+ * Per-model, per-machine timing calibration measured by the {@code ai-index:calibrate} goal and pasted
+ * onto an {@code <aiDefinition>} via {@code <calibration>}. It makes the plan's time estimate reflect the
+ * actual hardware (GPU/CPU, quant, context) instead of the built-in reference-CPU coefficients.
+ *
+ * <p>All values default to {@code 0}, which means "not calibrated": the estimator then falls back to its
+ * built-in model. The calibration is used only when {@link #getPrefillTokensPerSecond()} and
+ * {@link #getDecodeTokensPerSecond()} are both {@code > 0}.</p>
+ *
+ * <p><strong>Note:</strong> this class must remain a mutable JavaBean with setters because the Maven
+ * plugin framework populates it via reflection. {@code toString} is generated by Lombok;
+ * {@code equals}/{@code hashCode} are intentionally NOT generated (mutable configuration data).</p>
+ */
+@SuppressWarnings({"NullAway.Init", "initialization.fields.uninitialized"})
+@ToString
+public class AiCalibration {
+
+    /** Creates a new {@link AiCalibration}. */
+    public AiCalibration() {
+        // no-op
+    }
+
+    /** Measured prefill (prompt-processing) throughput in tokens per second; {@code 0} = not calibrated. */
+    private double prefillTokensPerSecond;
+
+    /** Measured decode (answer-generation) throughput in tokens per second; {@code 0} = not calibrated. */
+    private double decodeTokensPerSecond;
+
+    /** Measured characters per token for this model on the sampled source; {@code 0} = use the default. */
+    private double charsPerToken;
+
+    /**
+     * Returns the measured prefill throughput (tokens/second), or {@code 0} when not calibrated.
+     *
+     * @return the prefill tokens per second
+     */
+    public double getPrefillTokensPerSecond() {
+        return prefillTokensPerSecond;
+    }
+
+    /**
+     * Sets the measured prefill throughput (tokens/second).
+     *
+     * @param prefillTokensPerSecond the prefill tokens per second
+     */
+    public void setPrefillTokensPerSecond(final double prefillTokensPerSecond) {
+        this.prefillTokensPerSecond = prefillTokensPerSecond;
+    }
+
+    /**
+     * Returns the measured decode throughput (tokens/second), or {@code 0} when not calibrated.
+     *
+     * @return the decode tokens per second
+     */
+    public double getDecodeTokensPerSecond() {
+        return decodeTokensPerSecond;
+    }
+
+    /**
+     * Sets the measured decode throughput (tokens/second).
+     *
+     * @param decodeTokensPerSecond the decode tokens per second
+     */
+    public void setDecodeTokensPerSecond(final double decodeTokensPerSecond) {
+        this.decodeTokensPerSecond = decodeTokensPerSecond;
+    }
+
+    /**
+     * Returns the measured characters per token, or {@code 0} when not measured.
+     *
+     * @return the characters per token
+     */
+    public double getCharsPerToken() {
+        return charsPerToken;
+    }
+
+    /**
+     * Sets the measured characters per token.
+     *
+     * @param charsPerToken the characters per token
+     */
+    public void setCharsPerToken(final double charsPerToken) {
+        this.charsPerToken = charsPerToken;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java
new file mode 100644
index 0000000..0741395
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounter.java
@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import lombok.ToString;
+
+/**
+ * One deterministic "fact" counter for an oversize routing rule: a human-readable {@link #label} paired
+ * with a {@link #pattern} (a Java regular expression). The number of non-overlapping matches of
+ * {@code pattern} across the <em>whole</em> source is reported next to {@code label} in the generated
+ * body, giving exact counts the AI cannot reliably produce (it never sees the whole file when the source
+ * is chunked/sampled).
+ *
+ * <p>Language-agnostic by design: the meaning is entirely in the regex the operator writes, so the same
+ * mechanism counts {@code (?m)^\s*INSERT\b} rows in a SQL dump, {@code \bboolean\b} occurrences in Java,
+ * or {@code (?m)^\s*def\b} functions in Python. Multi-line matching is opt-in via the inline flag
+ * {@code (?m)} in the pattern; no flags are applied implicitly.</p>
+ *
+ * <p><strong>Note:</strong> this class must remain a mutable JavaBean with setters because the Maven
+ * plugin framework populates it via reflection from the {@code <facts>} configuration list.</p>
+ *
+ * <p>{@code toString} is generated by Lombok for build-log diagnostics; {@code equals}/{@code hashCode}
+ * are intentionally NOT generated (instances are configuration data managed by position in a list, and
+ * the mutable JavaBean shape makes value semantics unsafe).</p>
+ *
+ * @see AiFactExtractor
+ */
+@SuppressWarnings({"NullAway.Init", "initialization.fields.uninitialized"})
+@ToString
+public class AiFactCounter {
+
+    /** Creates a new {@link AiFactCounter}. */
+    public AiFactCounter() {
+        // no-op
+    }
+
+    /** Human-readable label shown next to the count (e.g. {@code "INSERT rows"}). */
+    private String label;
+
+    /** Java regular expression whose non-overlapping match count over the whole source is reported. */
+    private String pattern;
+
+    /**
+     * Returns the human-readable label.
+     *
+     * @return the label
+     */
+    public String getLabel() {
+        return label;
+    }
+
+    /**
+     * Sets the human-readable label.
+     *
+     * @param label the label
+     */
+    public void setLabel(final String label) {
+        this.label = label;
+    }
+
+    /**
+     * Returns the counting regular expression.
+     *
+     * @return the pattern
+     */
+    public String getPattern() {
+        return pattern;
+    }
+
+    /**
+     * Sets the counting regular expression.
+     *
+     * @param pattern the pattern
+     */
+    public void setPattern(final String pattern) {
+        this.pattern = pattern;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java
new file mode 100644
index 0000000..86b790d
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinition.java
@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import java.util.List;
+import lombok.ToString;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * A named, reusable group of {@link AiFactCounter}s, registered in the goal's {@code <factDefinitions>}
+ * list and referenced from a routing rule by {@link AiFieldGenerationConfig#getFactsKey() factsKey}.
+ *
+ * <p>Mirrors {@code <promptDefinitions>}: define a fact set once (e.g. {@code java-facts},
+ * {@code sql-facts}) and reference it from every rule that needs it, instead of repeating the same
+ * {@code <facts>} block inline on each rule.</p>
+ *
+ * <p><strong>Note:</strong> this class must remain a mutable JavaBean with setters because the Maven
+ * plugin framework populates it via reflection. {@code toString} is generated by Lombok;
+ * {@code equals}/{@code hashCode} are intentionally NOT generated (instances are configuration data
+ * managed by key in a lookup, and the mutable JavaBean shape makes value semantics unsafe).</p>
+ *
+ * @see AiFactDefinitionSupport
+ * @see AiFactCounter
+ */
+@SuppressWarnings({"NullAway.Init", "initialization.fields.uninitialized"})
+@ToString
+public class AiFactDefinition {
+
+    /** Creates a new {@link AiFactDefinition}. */
+    public AiFactDefinition() {
+        // no-op
+    }
+
+    /** Lookup key referenced by {@link AiFieldGenerationConfig#getFactsKey()}. */
+    private String key;
+
+    /** The fact counters this group contributes. */
+    private @Nullable List<AiFactCounter> facts;
+
+    /**
+     * Returns the lookup key.
+     *
+     * @return the key
+     */
+    public String getKey() {
+        return key;
+    }
+
+    /**
+     * Sets the lookup key.
+     *
+     * @param key the key
+     */
+    public void setKey(final String key) {
+        this.key = key;
+    }
+
+    /**
+     * Returns the fact counters, or {@code null} when none are configured.
+     *
+     * @return the fact counters, or {@code null}
+     */
+    public @Nullable List<AiFactCounter> getFacts() {
+        return facts;
+    }
+
+    /**
+     * Sets the fact counters.
+     *
+     * @param facts the fact counters
+     */
+    public void setFacts(final @Nullable List<AiFactCounter> facts) {
+        this.facts = facts;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java
new file mode 100644
index 0000000..3178fa2
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupport.java
@@ -0,0 +1,103 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Resolves reusable {@link AiFactDefinition} groups by key and applies them to routing rules.
+ *
+ * <p>Built from the goal's {@code <factDefinitions>} list, this is the fact-set equivalent of
+ * {@code AiModelDefinitionSupport}: a rule references a shared fact group via
+ * {@link AiFieldGenerationConfig#getFactsKey() factsKey} instead of repeating the same {@code <facts>}
+ * block inline. {@link #resolveFactsKeys(Iterable)} copies the referenced group's counters onto each
+ * rule (setting {@link AiFieldGenerationConfig#setFacts(List)}) so the rest of the pipeline reads the
+ * already-resolved {@code getFacts()} uniformly, whether the counters were inline or shared.</p>
+ *
+ * <p>Every entry must have a non-null {@code key} (a null key throws {@link NullPointerException} naming
+ * the index); a {@code factsKey} that matches no group throws {@link IllegalArgumentException}. Mojos
+ * wrap these in {@link org.apache.maven.plugin.MojoExecutionException} so a misconfigured POM fails fast
+ * as a user error.</p>
+ *
+ * @see AiFactDefinition
+ * @see AiFieldGenerationConfig#getFactsKey()
+ */
+@ToString
+public final class AiFactDefinitionSupport {
+
+    /** Error message prefix used when a rule's {@code factsKey} matches no registered definition. */
+    private static final String MISSING_DEFINITION_MESSAGE_PREFIX = "Missing fact definition for factsKey: ";
+
+    private final Map<String, List<AiFactCounter>> factsByKey;
+    private final Java8CompatibilityHelper compatibilityHelper = new Java8CompatibilityHelper();
+
+    /**
+     * Builds a new {@code AiFactDefinitionSupport} from the supplied definitions list.
+     *
+     * @param definitions list of fact definitions; may be {@code null} or empty (no shared groups);
+     *                    every entry must have a non-null {@code key}
+     * @throws NullPointerException if any entry has a {@code null} {@code key}
+     */
+    public AiFactDefinitionSupport(final @Nullable List<AiFactDefinition> definitions) {
+        if (definitions == null) {
+            this.factsByKey = new HashMap<>(compatibilityHelper.hashMapCapacityFor(0));
+            return;
+        }
+        final int count = definitions.size();
+        this.factsByKey = new HashMap<>(compatibilityHelper.hashMapCapacityFor(count));
+        for (int i = 0; i < count; i++) {
+            final AiFactDefinition definition = definitions.get(i);
+            final int index = i;
+            Objects.requireNonNull(
+                    definition.getKey(),
+                    () -> "factDefinitions[" + index + "].key is required (bad entry: " + definition + ")");
+            final List<AiFactCounter> facts = definition.getFacts();
+            // Normalize a group that declared no counters to an empty list, so the map value is never null
+            // (a group that references no facts is a no-op, same as an empty <facts>).
+            factsByKey.put(definition.getKey(), facts != null ? facts : Collections.emptyList());
+        }
+    }
+
+    /**
+     * Returns the fact counters registered under {@code key} (empty when the group declared none).
+     *
+     * @param key the fact-definition key to look up
+     * @return the counters for that group; never {@code null}
+     * @throws IllegalArgumentException if no group is registered for {@code key}
+     */
+    public List<AiFactCounter> facts(final String key) {
+        final List<AiFactCounter> facts = factsByKey.get(key);
+        if (facts == null) {
+            throw new IllegalArgumentException(MISSING_DEFINITION_MESSAGE_PREFIX + key);
+        }
+        return facts;
+    }
+
+    /**
+     * Resolves each rule's {@link AiFieldGenerationConfig#getFactsKey() factsKey} to the referenced shared
+     * counters, overwriting the rule's inline {@code facts}. Rules without a {@code factsKey} are left
+     * untouched (their inline {@code <facts>}, if any, stand).
+     *
+     * @param rules the routing rules to resolve in place; {@code null} entries are skipped
+     * @throws IllegalArgumentException if a rule's {@code factsKey} matches no registered group
+     */
+    public void resolveFactsKeys(final Iterable<AiFieldGenerationConfig> rules) {
+        for (final AiFieldGenerationConfig rule : rules) {
+            if (rule == null) {
+                continue;
+            }
+            final String factsKey = rule.getFactsKey();
+            if (factsKey != null) {
+                rule.setFacts(facts(factsKey));
+            }
+        }
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java
new file mode 100644
index 0000000..95f714e
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractor.java
@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.regex.PatternSyntaxException;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Computes a deterministic, language-agnostic "facts" block from a list of {@link AiFactCounter}s.
+ *
+ * <p>Each counter contributes one {@code label: count} entry, where {@code count} is the number of
+ * non-overlapping matches of the counter's regex across the <em>whole</em> source. This gives exact,
+ * model-free counts (rows, tables, boolean fields, functions, …) that a chunked/sampled AI summary
+ * cannot reliably produce, and is prepended to the AI body on the oversize path. Pure; no I/O.</p>
+ */
+public final class AiFactExtractor {
+
+    /** Header prefixing the facts line, marking the counts as exact and whole-file (not AI-estimated). */
+    public static final String FACTS_HEADER = "**Facts (exact, whole file):** ";
+
+    /** Separator between {@code label} and its count. */
+    public static final String LABEL_COUNT_SEPARATOR = ": ";
+
+    /** Separator between consecutive {@code label: count} entries. */
+    public static final String ENTRY_SEPARATOR = "; ";
+
+    /** Trailing separator between the facts line and the AI body that follows it. */
+    public static final String FACTS_SUFFIX = "\n\n";
+
+    /** Utility class; not instantiable. */
+    private AiFactExtractor() {
+        // no-op
+    }
+
+    /**
+     * Builds the facts block for the given counters over {@code source}, or an empty string when there are
+     * no counters. Counters with a {@code null} label or pattern are skipped (they are rejected up front by
+     * {@link #validate(List)}).
+     *
+     * @param counters the configured fact counters; {@code null} or empty yields an empty string
+     * @param source   the full source text the regexes are counted over
+     * @return the facts block (ending in a blank line), or {@code ""} when there is nothing to report
+     */
+    public static String factsBlock(final @Nullable List<AiFactCounter> counters, final String source) {
+        if (counters == null || counters.isEmpty()) {
+            return "";
+        }
+        final StringBuilder sb = new StringBuilder(64);
+        for (final AiFactCounter counter : counters) {
+            if (counter == null || counter.getLabel() == null || counter.getPattern() == null) {
+                continue;
+            }
+            if (sb.length() > 0) {
+                sb.append(ENTRY_SEPARATOR);
+            }
+            sb.append(counter.getLabel())
+                    .append(LABEL_COUNT_SEPARATOR)
+                    .append(countMatches(counter.getPattern(), source));
+        }
+        if (sb.length() == 0) {
+            return "";
+        }
+        return FACTS_HEADER + sb + FACTS_SUFFIX;
+    }
+
+    /**
+     * Validates that every counter has a non-null label and a compilable pattern, throwing
+     * {@link IllegalArgumentException} so the build fails fast on a misconfigured {@code <facts>} list.
+     *
+     * @param counters the configured fact counters; {@code null} or empty is valid (nothing to check)
+     * @throws IllegalArgumentException if a counter is missing its label/pattern or has an invalid regex
+     */
+    public static void validate(final @Nullable List<AiFactCounter> counters) {
+        if (counters == null) {
+            return;
+        }
+        for (final AiFactCounter counter : counters) {
+            if (counter == null) {
+                continue;
+            }
+            if (counter.getLabel() == null) {
+                throw new IllegalArgumentException("A fact counter must have a label: " + counter);
+            }
+            if (counter.getPattern() == null) {
+                throw new IllegalArgumentException("A fact counter must have a pattern: " + counter);
+            }
+            try {
+                Pattern.compile(counter.getPattern());
+            } catch (final PatternSyntaxException e) {
+                throw new IllegalArgumentException(
+                        "Invalid fact pattern for label '" + counter.getLabel() + "': " + e.getMessage(), e);
+            }
+        }
+    }
+
+    /**
+     * Counts the non-overlapping matches of {@code pattern} in {@code source}.
+     *
+     * @param pattern the regular expression
+     * @param source  the text to search
+     * @return the number of matches (zero-width matches, e.g. {@code (?m)^}, count once per position)
+     */
+    private static int countMatches(final String pattern, final String source) {
+        final Matcher matcher = Pattern.compile(pattern).matcher(source);
+        int count = 0;
+        while (matcher.find()) {
+            count++;
+        }
+        return count;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java
index 6f9929f..b45baef 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfig.java
@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 package net.ladenthin.maven.llamacpp.aiindex.config;
 
+import java.util.List;
 import lombok.ToString;
 import org.jspecify.annotations.Nullable;
 
@@ -75,6 +76,40 @@ public AiFieldGenerationConfig() {
      */
     private boolean skip;
 
+    /**
+     * What to do when a matched file is larger than its routed model's context window. One of
+     * {@code fail} (default — abort the build), {@code sample} (trim to the window, summarize the head),
+     * {@code mapReduce} (chunk + summarize each + combine), {@code deterministic} (model-free metadata
+     * body). Parsed by {@link AiOversizeStrategy#fromConfig(String)}; {@code null}/blank = {@code fail}.
+     */
+    private @Nullable String onOversize;
+
+    /**
+     * For {@link AiOversizeStrategy#MAP_REDUCE}: the maximum number of chunks to summarize. {@code 0}
+     * (default) = unbounded (process every chunk). A positive value bounds the run time by sampling that
+     * many representative chunks (head + evenly spaced + tail) across the file.
+     */
+    private int maxChunks;
+
+    /**
+     * Optional deterministic "fact" counters ({@code <facts>}). When set, each counter's
+     * {@code label: <match count over the whole file>} is prepended to the generated body of <em>every</em>
+     * file this rule matches (oversize or not) — exact, language-agnostic structural counts (e.g. SQL
+     * {@code INSERT} rows / tables / views, Java types / {@code boolean} fields) that give downstream
+     * agents authoritative numbers a sampled AI summary cannot reliably produce. {@code null}/empty = no
+     * facts block. See {@link AiFactExtractor}.
+     */
+    private @Nullable List<AiFactCounter> facts;
+
+    /**
+     * Optional reference to a shared {@code <factDefinitions>} group by its key ({@code <factsKey>}),
+     * instead of repeating an inline {@link #facts} block. Resolved before indexing by
+     * {@link AiFactDefinitionSupport#resolveFactsKeys(Iterable)}, which copies the referenced counters
+     * onto {@link #facts} (overwriting any inline value). {@code null} = use the inline {@code <facts>}
+     * (or none).
+     */
+    private @Nullable String factsKey;
+
     /**
      * Returns the optional rule id (label), or {@code null} when not set.
      *
@@ -200,4 +235,86 @@ public boolean isSkip() {
     public void setSkip(final boolean skip) {
         this.skip = skip;
     }
+
+    /**
+     * Returns the raw {@code onOversize} config token, or {@code null} when not set.
+     *
+     * @return the oversize-strategy token, or {@code null}
+     */
+    public @Nullable String getOnOversize() {
+        return onOversize;
+    }
+
+    /**
+     * Sets the {@code onOversize} config token (one of {@code fail}/{@code sample}/{@code mapReduce}/{@code deterministic}).
+     *
+     * @param onOversize the oversize-strategy token
+     */
+    public void setOnOversize(final @Nullable String onOversize) {
+        this.onOversize = onOversize;
+    }
+
+    /**
+     * Returns the parsed oversize strategy ({@link AiOversizeStrategy#FAIL} when unset/blank).
+     *
+     * @return the oversize strategy
+     * @throws IllegalArgumentException if {@code onOversize} is non-blank and matches no strategy
+     */
+    public AiOversizeStrategy getOversizeStrategy() {
+        return AiOversizeStrategy.fromConfig(onOversize);
+    }
+
+    /**
+     * Returns the map-reduce chunk cap ({@code 0} = unbounded).
+     *
+     * @return the maximum number of chunks
+     */
+    public int getMaxChunks() {
+        return maxChunks;
+    }
+
+    /**
+     * Sets the map-reduce chunk cap ({@code 0} = unbounded).
+     *
+     * @param maxChunks the maximum number of chunks
+     */
+    public void setMaxChunks(final int maxChunks) {
+        this.maxChunks = maxChunks;
+    }
+
+    /**
+     * Returns the optional deterministic fact counters, or {@code null} when none are configured.
+     *
+     * @return the fact counters, or {@code null}
+     */
+    public @Nullable List<AiFactCounter> getFacts() {
+        return facts;
+    }
+
+    /**
+     * Sets the deterministic fact counters.
+     *
+     * @param facts the fact counters
+     */
+    public void setFacts(final @Nullable List<AiFactCounter> facts) {
+        this.facts = facts;
+    }
+
+    /**
+     * Returns the shared fact-definition reference key, or {@code null} when not set.
+     *
+     * @return the facts key, or {@code null}
+     */
+    public @Nullable String getFactsKey() {
+        return factsKey;
+    }
+
+    /**
+     * Sets the shared fact-definition reference key.
+     *
+     * @param factsKey the facts key
+     */
+    public void setFactsKey(final @Nullable String factsKey) {
+        this.factsKey = factsKey;
+    }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java
index d2cf2a7..059df68 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelector.java
@@ -79,6 +79,10 @@ public void validate(final Iterable<AiFieldGenerationConfig> configs) {
             if (config == null) {
                 continue;
             }
+            // Fail fast on an unknown onOversize token (throws IllegalArgumentException naming the value).
+            config.getOversizeStrategy();
+            // Fail fast on a malformed <facts> counter (missing label/pattern or an invalid regex).
+            AiFactExtractor.validate(config.getFacts());
             if (config.isFallback()) {
                 fallbackCount++;
                 if (config.isSkip()) {
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java
index 0ed14a7..fbd9b1f 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiGenerationConfig.java
@@ -254,6 +254,9 @@ public AiGenerationConfig() {
     private List<String> drySequenceBreakers = new ArrayList<>();
     private List<String> stopStrings = new ArrayList<>();
 
+    /** Optional per-machine timing calibration; {@code null} = use the estimator's built-in model. */
+    private @Nullable AiCalibration calibration;
+
     /**
      * Returns the GGUF model file path.
      *
@@ -760,4 +763,22 @@ public void setDrySequenceBreakers(final @Nullable List<String> drySequenceBreak
     public void setStopStrings(final @Nullable List<String> stopStrings) {
         this.stopStrings = stopStrings != null ? stopStrings : new ArrayList<>();
     }
+
+    /**
+     * Returns the per-machine timing calibration, or {@code null} when not calibrated.
+     *
+     * @return the calibration, or {@code null}
+     */
+    public @Nullable AiCalibration getCalibration() {
+        return calibration;
+    }
+
+    /**
+     * Sets the per-machine timing calibration.
+     *
+     * @param calibration the calibration
+     */
+    public void setCalibration(final @Nullable AiCalibration calibration) {
+        this.calibration = calibration;
+    }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java
index 18090d3..fbba4df 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinition.java
@@ -67,6 +67,9 @@ public AiModelDefinition() {
     private @Nullable List<String> drySequenceBreakers;
     private @Nullable List<String> stopStrings;
 
+    /** Optional per-machine timing calibration ({@code <calibration>}), measured by {@code ai-index:calibrate}. */
+    private @Nullable AiCalibration calibration;
+
     /**
      * Returns the unique lookup key for this definition.
      *
@@ -585,4 +588,22 @@ public void setDrySequenceBreakers(final @Nullable Collection<String> drySequenc
     public void setStopStrings(final @Nullable Collection<String> stopStrings) {
         this.stopStrings = stopStrings != null ? new ArrayList<>(stopStrings) : null;
     }
+
+    /**
+     * Returns the per-machine timing calibration, or {@code null} when not calibrated.
+     *
+     * @return the calibration, or {@code null}
+     */
+    public @Nullable AiCalibration getCalibration() {
+        return calibration;
+    }
+
+    /**
+     * Sets the per-machine timing calibration.
+     *
+     * @param calibration the calibration
+     */
+    public void setCalibration(final @Nullable AiCalibration calibration) {
+        this.calibration = calibration;
+    }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java
index a412dc5..980d375 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupport.java
@@ -129,6 +129,7 @@ private static AiGenerationConfig toConfig(final AiModelDefinition definition) {
         config.setDryAllowedLength(definition.getDryAllowedLength());
         config.setDryPenaltyLastN(definition.getDryPenaltyLastN());
         config.setDrySequenceBreakers(definition.getDrySequenceBreakers());
+        config.setCalibration(definition.getCalibration());
         return config;
     }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java
new file mode 100644
index 0000000..f20d728
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategy.java
@@ -0,0 +1,85 @@
+// @formatter:off
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+// @formatter:on
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * What to do when a source file is larger than its routed model's context window.
+ *
+ * <p>Configured per routing rule via {@code <onOversize>} (a string, parsed by
+ * {@link #fromConfig(String)}). The default is {@link #FAIL}: the build aborts and the user must route
+ * oversized files to a larger-context model (no automatic model choice). The other strategies let a rule
+ * deliberately handle oversized files:</p>
+ *
+ * <ul>
+ *   <li>{@link #SAMPLE} — feed only the head of the file (trimmed to the window) in one call; fast,
+ *       bounded, good for repetitive data where the head represents the whole.</li>
+ *   <li>{@link #MAP_REDUCE} — split the file into window-sized chunks at line boundaries, summarize each,
+ *       then combine the partial summaries in one final call; processes far more of the file than a
+ *       single window, with a {@code maxChunks} cap to bound the time.</li>
+ *   <li>{@link #DETERMINISTIC} — no model at all: emit a deterministic body (size, line count, head/tail
+ *       sample); instant, for pure data where no AI analysis is needed.</li>
+ * </ul>
+ */
+public enum AiOversizeStrategy {
+
+    /** Abort the build; the user must configure a larger-context model (default). */
+    FAIL("fail"),
+
+    /** Trim the source to the window and summarize the head in a single call. */
+    SAMPLE("sample"),
+
+    /** Chunk at line boundaries, summarize each chunk, then combine the partial summaries. */
+    MAP_REDUCE("mapReduce"),
+
+    /** Emit a model-free deterministic body (metadata + head/tail sample). */
+    DETERMINISTIC("deterministic");
+
+    /** The strategy applied when none is configured. */
+    public static final AiOversizeStrategy DEFAULT = FAIL;
+
+    /** The {@code <onOversize>} config token for this strategy. */
+    private final String configValue;
+
+    AiOversizeStrategy(final String configValue) {
+        this.configValue = configValue;
+    }
+
+    /**
+     * Returns the {@code <onOversize>} config token (e.g. {@code "mapReduce"}).
+     *
+     * @return the config token
+     */
+    public String configValue() {
+        return configValue;
+    }
+
+    /**
+     * Parses a {@code <onOversize>} config value (case-insensitive). {@code null} or blank yields
+     * {@link #DEFAULT}.
+     *
+     * @param value the configured value, or {@code null}
+     * @return the matching strategy
+     * @throws IllegalArgumentException if {@code value} is non-blank and matches no strategy
+     */
+    public static AiOversizeStrategy fromConfig(final @Nullable String value) {
+        if (value == null) {
+            return DEFAULT;
+        }
+        final String trimmed = value.trim();
+        if (trimmed.isEmpty()) {
+            return DEFAULT;
+        }
+        for (final AiOversizeStrategy strategy : values()) {
+            if (strategy.configValue.equalsIgnoreCase(trimmed)) {
+                return strategy;
+            }
+        }
+        throw new IllegalArgumentException(
+                "Unknown onOversize strategy: '" + value + "' (expected one of fail/sample/mapReduce/deterministic)");
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurement.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurement.java
new file mode 100644
index 0000000..a227761
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurement.java
@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.indexer;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord;
+
+/**
+ * The result of one model's calibration measurement (see {@link AiCalibrationRunner}): the load time and
+ * the measured near-window throughput that becomes the model's {@code <calibration>}, plus the mid-window
+ * prefill rate for a curvature hint.
+ *
+ * <p>Record-shaped value type marked {@link ConvertToRecord} for the future Java&nbsp;17+ migration.</p>
+ */
+@ConvertToRecord
+@ToString
+@EqualsAndHashCode
+public final class AiCalibrationMeasurement {
+
+    private final double loadSeconds;
+    private final double prefillTokensPerSecond;
+    private final double decodeTokensPerSecond;
+    private final double charsPerToken;
+    private final double midPrefillTokensPerSecond;
+
+    /**
+     * Creates a new {@link AiCalibrationMeasurement}.
+     *
+     * @param loadSeconds               wall-clock seconds for model load + first generation
+     * @param prefillTokensPerSecond    near-window prefill throughput (the calibration headline)
+     * @param decodeTokensPerSecond     near-window decode throughput
+     * @param charsPerToken             measured characters per token at the near-window size
+     * @param midPrefillTokensPerSecond mid-window prefill throughput (for a curvature hint)
+     */
+    public AiCalibrationMeasurement(
+            final double loadSeconds,
+            final double prefillTokensPerSecond,
+            final double decodeTokensPerSecond,
+            final double charsPerToken,
+            final double midPrefillTokensPerSecond) {
+        this.loadSeconds = loadSeconds;
+        this.prefillTokensPerSecond = prefillTokensPerSecond;
+        this.decodeTokensPerSecond = decodeTokensPerSecond;
+        this.charsPerToken = charsPerToken;
+        this.midPrefillTokensPerSecond = midPrefillTokensPerSecond;
+    }
+
+    /**
+     * Returns the load + first-generation wall-clock seconds.
+     *
+     * @return the load seconds
+     */
+    public double loadSeconds() {
+        return loadSeconds;
+    }
+
+    /**
+     * Returns the near-window prefill throughput (tokens/second).
+     *
+     * @return the prefill tokens per second
+     */
+    public double prefillTokensPerSecond() {
+        return prefillTokensPerSecond;
+    }
+
+    /**
+     * Returns the near-window decode throughput (tokens/second).
+     *
+     * @return the decode tokens per second
+     */
+    public double decodeTokensPerSecond() {
+        return decodeTokensPerSecond;
+    }
+
+    /**
+     * Returns the measured characters per token.
+     *
+     * @return the characters per token
+     */
+    public double charsPerToken() {
+        return charsPerToken;
+    }
+
+    /**
+     * Returns the mid-window prefill throughput (tokens/second), for a curvature hint.
+     *
+     * @return the mid-window prefill tokens per second
+     */
+    public double midPrefillTokensPerSecond() {
+        return midPrefillTokensPerSecond;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunner.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunner.java
new file mode 100644
index 0000000..3f13c6b
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunner.java
@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.indexer;
+
+import java.io.IOException;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationTimings;
+
+/**
+ * Measures one model's per-machine timing for the {@code ai-index:calibrate} goal: it triggers the load,
+ * runs two representative generations (mid- and near-window sized), and reads the model's own measured
+ * prefill/decode throughput. Lives in the indexer layer because it builds requests and drives the
+ * provider; the mojo stays thin (orchestrate + format).
+ */
+public final class AiCalibrationRunner {
+
+    /** Fraction of the window used for the first (mid-size) calibration generation. */
+    private static final double MID_WINDOW_FRACTION = 0.5d;
+
+    /** Fraction of the window used for the second (near-window) calibration generation, the headline. */
+    private static final double NEAR_WINDOW_FRACTION = 0.9d;
+
+    /** Character length of the warmup prompt that triggers model load. */
+    private static final int WARMUP_SOURCE_CHARS = 200;
+
+    /** Lower bound on a calibration source length, so a tiny/mock window still generates something. */
+    private static final int MIN_CALIBRATION_SOURCE_CHARS = 200;
+
+    /** Nanoseconds per second, for the load-time measurement. */
+    private static final double NANOS_PER_SECOND = 1_000_000_000.0d;
+
+    /** Synthetic context file name used for the calibration requests. */
+    private static final String CALIBRATION_CONTEXT_NAME = "calibration-sample";
+
+    /** A representative code-like line repeated to synthesize a calibration source of a target length. */
+    private static final String SYNTHETIC_SOURCE_LINE =
+            "public final int value = compute(argument, offset) + 42; // calibration filler line\n";
+
+    /** Chars/token assumed in the wall-clock fallback when the model config does not set one. */
+    private static final double FALLBACK_CHARS_PER_TOKEN = 4.0d;
+
+    /** Floor on the derived decode duration (seconds) so the wall-clock fallback never divides by ~zero. */
+    private static final double MIN_DECODE_SECONDS = 0.001d;
+
+    /** Creates a new {@link AiCalibrationRunner}. */
+    public AiCalibrationRunner() {
+        // no-op
+    }
+
+    /**
+     * Runs the warmup + two sized generations against {@code provider} and returns the measurement.
+     *
+     * @param provider  the (already built) provider for the model being calibrated
+     * @param config    the model's generation config (for the window size)
+     * @param promptKey a representative prompt key routed to this model
+     * @param prep      prompt preparation (for the base-prompt length / window)
+     * @return the measurement (load time + near/mid throughput + chars-per-token)
+     * @throws IOException if the provider throws during generation
+     */
+    public AiCalibrationMeasurement measure(
+            final AiGenerationProvider provider,
+            final AiGenerationConfig config,
+            final String promptKey,
+            final AiPromptPreparationSupport prep)
+            throws IOException {
+        final Path contextFile = Paths.get(CALIBRATION_CONTEXT_NAME);
+        final int basePromptLength = prep.getBasePromptLength(promptKey, contextFile);
+        final long availableSourceChars = AiInputWindowCalculator.availableSourceChars(config, basePromptLength);
+        final int midChars = clampSourceChars((long) (availableSourceChars * MID_WINDOW_FRACTION));
+        final int nearChars = clampSourceChars((long) (availableSourceChars * NEAR_WINDOW_FRACTION));
+        final AiMdHeader header = new AiMdHeader(CALIBRATION_CONTEXT_NAME, "1.0", "", "", "", "", "", "file");
+        // The warmup and the decode probe use the SAME tiny source, so the probe reuses the warmup's
+        // prefill KV (prompt cache) and its wall-clock is close to pure decode.
+        final String tinySource = syntheticSource(WARMUP_SOURCE_CHARS);
+
+        final long loadStartNanos = System.nanoTime();
+        provider.generateWithTimings(request(promptKey, contextFile, tinySource, header));
+        final double loadSeconds = (System.nanoTime() - loadStartNanos) / NANOS_PER_SECOND;
+
+        final long midStartNanos = System.nanoTime();
+        final AiGenerationTimings mid =
+                provider.generateWithTimings(request(promptKey, contextFile, syntheticSource(midChars), header));
+        final double midWallSeconds = (System.nanoTime() - midStartNanos) / NANOS_PER_SECOND;
+
+        final long nearStartNanos = System.nanoTime();
+        final AiGenerationTimings near =
+                provider.generateWithTimings(request(promptKey, contextFile, syntheticSource(nearChars), header));
+        final double nearWallSeconds = (System.nanoTime() - nearStartNanos) / NANOS_PER_SECOND;
+
+        // Preferred path: the provider reports the model's OWN measured throughput (exact tokens/sec).
+        if (near.prefillTokensPerSecond() > 0.0d) {
+            final double charsPerToken = near.promptTokens() > 0 ? (double) nearChars / near.promptTokens() : 0.0d;
+            return new AiCalibrationMeasurement(
+                    loadSeconds,
+                    near.prefillTokensPerSecond(),
+                    near.decodeTokensPerSecond(),
+                    charsPerToken,
+                    mid.prefillTokensPerSecond());
+        }
+
+        // Fallback (no reported timings, e.g. mock): estimate by wall-clock. Only now do the decode probe
+        // (a TINY prompt whose prefill KV is reused from the warmup, so its wall-clock is ~pure decode; its
+        // generated text gives the ACTUAL output size).
+        final long probeStartNanos = System.nanoTime();
+        final AiGenerationTimings probe =
+                provider.generateWithTimings(request(promptKey, contextFile, tinySource, header));
+        final double probeWallSeconds = (System.nanoTime() - probeStartNanos) / NANOS_PER_SECOND;
+        return wallClockFallback(
+                loadSeconds, midChars, nearChars, midWallSeconds, nearWallSeconds, probe, probeWallSeconds, config);
+    }
+
+    /**
+     * Derives throughput from wall-clock timing when the binding reports none.
+     *
+     * <p><b>Prefill</b> comes from the mid&rarr;near difference (decode cancels because both runs use the
+     * same output budget). <b>Decode</b> comes from the tiny probe run: its wall-clock minus the tiny
+     * prompt's (negligible) prefill, divided by the <em>actual</em> number of generated tokens (from the
+     * probe's returned text length &divide; chars-per-token) &mdash; not an assumed output budget.</p>
+     *
+     * @param loadSeconds     the measured load + first-generation seconds
+     * @param midChars        the mid-window source length
+     * @param nearChars       the near-window source length
+     * @param midWallSeconds  wall-clock seconds for the mid-window generation
+     * @param nearWallSeconds wall-clock seconds for the near-window generation
+     * @param probe           the tiny decode-probe result (its text is the actual generated output)
+     * @param probeWallSeconds wall-clock seconds for the decode probe
+     * @param config          the model config (chars/token)
+     * @return the measurement derived from wall-clock timing
+     */
+    private static AiCalibrationMeasurement wallClockFallback(
+            final double loadSeconds,
+            final int midChars,
+            final int nearChars,
+            final double midWallSeconds,
+            final double nearWallSeconds,
+            final AiGenerationTimings probe,
+            final double probeWallSeconds,
+            final AiGenerationConfig config) {
+        final double charsPerToken =
+                config.getCharsPerToken() > 0 ? config.getCharsPerToken() : FALLBACK_CHARS_PER_TOKEN;
+        final double midTokens = midChars / charsPerToken;
+        final double nearTokens = nearChars / charsPerToken;
+        final double deltaTokens = nearTokens - midTokens;
+        final double deltaWall = nearWallSeconds - midWallSeconds;
+        final double prefillTps = deltaTokens > 0.0d && deltaWall > 0.0d ? deltaTokens / deltaWall : 0.0d;
+
+        // Decode from the tiny probe: subtract its (tiny) prefill, divide by the ACTUAL generated tokens.
+        final double probePromptTokens = WARMUP_SOURCE_CHARS / charsPerToken;
+        final double probePrefillSeconds = prefillTps > 0.0d ? probePromptTokens / prefillTps : 0.0d;
+        final double decodeSeconds = Math.max(MIN_DECODE_SECONDS, probeWallSeconds - probePrefillSeconds);
+        final double outputTokens = probe.text().length() / charsPerToken;
+        final double decodeTps = outputTokens > 0.0d ? outputTokens / decodeSeconds : 0.0d;
+
+        return new AiCalibrationMeasurement(loadSeconds, prefillTps, decodeTps, charsPerToken, prefillTps);
+    }
+
+    /**
+     * Returns the window size (source chars) used for calibration, for the caller's log line.
+     *
+     * @param config    the model config
+     * @param promptKey a representative prompt key
+     * @param prep      prompt preparation
+     * @return the available source-character window
+     */
+    public long windowChars(
+            final AiGenerationConfig config, final String promptKey, final AiPromptPreparationSupport prep) {
+        final int basePromptLength = prep.getBasePromptLength(promptKey, Paths.get(CALIBRATION_CONTEXT_NAME));
+        return AiInputWindowCalculator.availableSourceChars(config, basePromptLength);
+    }
+
+    private static int clampSourceChars(final long chars) {
+        return (int) Math.max(MIN_CALIBRATION_SOURCE_CHARS, Math.min(chars, Integer.MAX_VALUE));
+    }
+
+    private static String syntheticSource(final int targetChars) {
+        final StringBuilder sb = new StringBuilder(targetChars + SYNTHETIC_SOURCE_LINE.length());
+        // A size-specific first line so the mid- and near-window sources DIFFER from the start; otherwise
+        // the shared repeated-line prefix lets the prompt cache reuse the earlier run's KV and the larger
+        // run finishes faster, breaking the prefill differential.
+        sb.append("// calibration sample of size ").append(targetChars).append('\n');
+        while (sb.length() < targetChars) {
+            sb.append(SYNTHETIC_SOURCE_LINE);
+        }
+        return sb.toString();
+    }
+
+    private static AiGenerationRequest request(
+            final String promptKey, final Path contextFile, final String source, final AiMdHeader header) {
+        return new AiGenerationRequest(promptKey, contextFile, source, header);
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupport.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupport.java
index e92d328..73c3be6 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupport.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupport.java
@@ -5,20 +5,26 @@
 
 import java.io.IOException;
 import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationResult;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
 import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPreparedPrompt;
 import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport;
 import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider;
+import net.ladenthin.maven.llamacpp.aiindex.support.AiDeterministicSummary;
 import net.ladenthin.maven.llamacpp.aiindex.support.AiGenerationTimeEstimator;
+import net.ladenthin.maven.llamacpp.aiindex.support.AiSourceChunker;
 import net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper;
 import org.apache.maven.plugin.logging.Log;
 
@@ -111,6 +117,64 @@ public class AiFieldGenerationSupport {
     /** Nanoseconds per second, used to convert the measured generation duration to whole seconds. */
     private static final long NANOS_PER_SECOND = 1_000_000_000L;
 
+    /** Leading/trailing lines shown in a {@link AiOversizeStrategy#DETERMINISTIC} body. */
+    private static final int DETERMINISTIC_SAMPLE_LINES = 20;
+
+    /** Upper bound on the character overlap between map-reduce chunks. */
+    private static final int MAP_REDUCE_OVERLAP_CHARS = 2000;
+
+    /** Fraction (1/n) of the chunk size used as overlap when smaller than {@link #MAP_REDUCE_OVERLAP_CHARS}. */
+    private static final int MAP_REDUCE_OVERLAP_DIVISOR = 20;
+
+    /** Minimum per-chunk source budget, so a tiny window never yields zero-length chunks. */
+    private static final int MIN_CHUNK_CHARS = 1000;
+
+    /**
+     * Safety headroom (percent) subtracted from the map-reduce window before sizing chunks and reduce
+     * batches. {@code charsPerToken} is only an <em>estimate</em>; token-dense content (e.g. SQL with
+     * many digits/punctuation, ~2.8 chars/token) tokenizes to more tokens than a char budget computed
+     * from a higher {@code charsPerToken} assumes, which would otherwise let a chunk overflow the model's
+     * context window at run time (the native layer then rejects the request). Shrinking the map-reduce
+     * window by this margin keeps chunks safely inside the window even when real density is up to this
+     * percent below the configured {@code charsPerToken}.
+     */
+    private static final int MAP_REDUCE_TOKEN_HEADROOM_PERCENT = 20;
+
+    /**
+     * Maximum number of partial summaries combined into a single reduce call. Bounds the reduce prompt
+     * size and guarantees the hierarchical reduce makes progress (fan-in {@code >= 2}) so it terminates.
+     */
+    private static final int MAX_REDUCE_FANIN = 16;
+
+    /** Label prefix for one partial summary inside a reduce prompt. */
+    private static final String REDUCE_PART_LABEL = "Part ";
+
+    /** Approximate per-partial label + separator overhead when packing a reduce batch to the window. */
+    private static final int REDUCE_LABEL_OVERHEAD_CHARS = 16;
+
+    /** Percent divisor used when applying {@link #MAP_REDUCE_TOKEN_HEADROOM_PERCENT}. */
+    private static final int PERCENT = 100;
+
+    /**
+     * Maximum number of times a single generation is retried with a smaller window after the provider
+     * rejects the prompt for exceeding the model's context. The char-based window is an estimate; on
+     * token-dense content that estimate can undershoot even outside map-reduce (e.g. a dense file that
+     * just "fits", or a {@code sample} head), so this is the last-resort safety net for the single-shot
+     * path — it degrades gracefully (trims a little more) instead of failing the whole build.
+     */
+    private static final int MAX_OVERFLOW_RETRIES = 3;
+
+    /** Window multiplier (percent) applied on each context-overflow retry, shrinking the prompt. */
+    private static final int OVERFLOW_RETRY_BACKOFF_PERCENT = 75;
+
+    /**
+     * Substring identifying a context-overflow error in the provider's exception message chain
+     * (llama.cpp: "request (N tokens) exceeds the available context size (M tokens)…"). Matched on the
+     * message rather than a binding-specific exception type to keep the indexer decoupled from the JNI
+     * binding.
+     */
+    private static final String CONTEXT_OVERFLOW_MARKER = "exceeds the available context size";
+
     // Maven plugin Log — its default toString prints implementation details
     // (logger configuration, output stream state); excluded from the rendered output.
     @ToString.Exclude
@@ -205,6 +269,32 @@ public AiGenerationResult processFieldGenerations(
             final AiPreparedPrompt preparedPrompt =
                     promptPreparationSupport.preparePrompt(request, effectiveMaxInputChars);
 
+            // Deterministic, whole-file "facts" (exact regex counts) are prepended to the body of EVERY
+            // file that configures <facts> - not just oversize ones - so downstream agents get exact
+            // structural counts in the summary. Computed once here over the FULL source ("" when unset).
+            final String factsPrefix = AiFactExtractor.factsBlock(fieldGeneration.getFacts(), sourceText);
+
+            // An oversized file (the source did not fit the window) is handled per the rule's onOversize
+            // strategy. DETERMINISTIC/MAP_REDUCE replace the single generation entirely; FAIL/SAMPLE fall
+            // through to the single-shot path below (the source was already trimmed to the window head).
+            if (preparedPrompt.trimmed()) {
+                final AiOversizeStrategy oversize = fieldGeneration.getOversizeStrategy();
+                if (oversize == AiOversizeStrategy.DETERMINISTIC) {
+                    body = factsPrefix
+                            + AiDeterministicSummary.body(
+                                    sourceText, contextName(contextFile), DETERMINISTIC_SAMPLE_LINES);
+                    log.info("Oversize " + contextType + " '" + contextFile + "' -> deterministic body (no model), "
+                            + sourceText.length() + " chars");
+                    continue;
+                }
+                if (oversize == AiOversizeStrategy.MAP_REDUCE) {
+                    body = factsPrefix
+                            + mapReduceSummarize(
+                                    fieldGeneration, contextFile, sourceText, baseHeader, effectiveMaxInputChars);
+                    continue;
+                }
+            }
+
             if (preparedPrompt.trimmed() && generationConfig.isWarnOnTrim()) {
                 log.warn("Trimmed AI input for " + contextType + TRIM_WARN_FIELD_LABEL + "body': " + contextFile
                         + " (source chars " + preparedPrompt.originalSourceLength()
@@ -213,14 +303,13 @@ public AiGenerationResult processFieldGenerations(
                         + ", max input chars " + effectiveMaxInputChars + ")");
             }
 
-            final AiGenerationRequest generationRequest = new AiGenerationRequest(
-                    fieldGeneration.getPromptKey(), contextFile, preparedPrompt.sourceText(), baseHeader);
-
             final int processedSourceChars = preparedPrompt.sourceText().length();
             final String sourceSizeKb = sourceText.length() < KIBIBYTES_DIVISOR
                     ? SIZE_BELOW_ONE_KIB_LABEL
                     : Integer.toString(sourceText.length() / KIBIBYTES_DIVISOR);
-            final long estimatedSeconds = timeEstimator.estimateSeconds(processedSourceChars);
+            // Use the model's measured <calibration> when present, so the live per-file ETA matches the
+            // (already calibrated) plan ETA instead of the built-in reference-CPU model.
+            final long estimatedSeconds = estimateSeconds(processedSourceChars, generationConfig);
             log.info(PROCESSING_LOG_PREFIX + contextType + " '" + contextFile + "'"
                     + PROCESSING_LOG_SIZE_INFIX + sourceSizeKb
                     + PROCESSING_LOG_TOKENS_INFIX + timeEstimator.estimatePromptTokens(processedSourceChars)
@@ -232,8 +321,10 @@ public AiGenerationResult processFieldGenerations(
                     + generationConfig.getTemperature() + ", maxInputChars="
                     + effectiveMaxInputChars);
             final long generationStartNanos = System.nanoTime();
-            body = generationProvider.generate(generationRequest);
+            final String generated = generateWithOverflowRetry(
+                    fieldGeneration.getPromptKey(), contextFile, sourceText, baseHeader, effectiveMaxInputChars);
             final long actualSeconds = (System.nanoTime() - generationStartNanos) / NANOS_PER_SECOND;
+            body = factsPrefix + generated;
 
             // Log the MEASURED wall-clock duration next to the estimate so real runs are directly
             // comparable across models/quants without a separate benchmark harness.
@@ -241,7 +332,7 @@ public AiGenerationResult processFieldGenerations(
                     + timeEstimator.formatDuration(actualSeconds) + GENERATED_LOG_ACTUAL_INFIX
                     + timeEstimator.formatDuration(estimatedSeconds) + GENERATED_LOG_SUFFIX);
 
-            if (compatibilityHelper.isBlank(body)) {
+            if (compatibilityHelper.isBlank(generated)) {
                 log.warn(EMPTY_OUTPUT_WARN_PREFIX + contextType + TRIM_WARN_FIELD_LABEL + fieldGeneration.getPromptKey()
                         + "': " + contextFile);
             }
@@ -250,6 +341,243 @@ public AiGenerationResult processFieldGenerations(
         return new AiGenerationResult(body);
     }
 
+    /**
+     * Summarizes an oversized source via map-reduce: split it into window-sized chunks at line boundaries
+     * (with overlap), summarize each chunk with the rule's prompt (the <em>map</em>), then combine the
+     * partial summaries via a {@link #reducePartials hierarchical reduce}. The {@code maxChunks} cap (when
+     * set) bounds the run time by sampling representative chunks across the file; {@code maxChunks <= 0}
+     * processes every chunk (the whole file).
+     *
+     * <p>The chunk window is shrunk by {@link #MAP_REDUCE_TOKEN_HEADROOM_PERCENT} so a token-dense chunk
+     * cannot overflow the model's context (see that constant's Javadoc).</p>
+     *
+     * @param fieldGeneration        the routing rule (prompt key + {@code maxChunks})
+     * @param contextFile            the source file path
+     * @param sourceText             the full source text
+     * @param baseHeader             the header passed through to each request
+     * @param effectiveMaxInputChars the per-call window budget
+     * @return the combined summary body
+     * @throws IOException if the provider throws during generation
+     */
+    private String mapReduceSummarize(
+            final AiFieldGenerationConfig fieldGeneration,
+            final Path contextFile,
+            final String sourceText,
+            final AiMdHeader baseHeader,
+            final int effectiveMaxInputChars)
+            throws IOException {
+        final int basePromptLength =
+                promptPreparationSupport.getBasePromptLength(fieldGeneration.getPromptKey(), contextFile);
+        // Reserve token-safety headroom: real chars/token can be below the configured charsPerToken for
+        // dense content, so size chunks (and every map/reduce prompt) against a shrunken window.
+        final int safeWindow =
+                effectiveMaxInputChars - (effectiveMaxInputChars * MAP_REDUCE_TOKEN_HEADROOM_PERCENT / PERCENT);
+        final int sourceBudget = Math.max(MIN_CHUNK_CHARS, safeWindow - basePromptLength);
+        final int overlap = Math.min(MAP_REDUCE_OVERLAP_CHARS, sourceBudget / MAP_REDUCE_OVERLAP_DIVISOR);
+        final List<String> chunks =
+                AiSourceChunker.chunk(sourceText, sourceBudget, overlap, fieldGeneration.getMaxChunks());
+        log.info("Oversize file '" + contextFile + "' -> mapReduce: " + sourceText.length() + " chars in "
+                + chunks.size() + " chunk(s)");
+        final List<String> partials = new ArrayList<>(chunks.size());
+        int index = 0;
+        for (final String chunk : chunks) {
+            index++;
+            partials.add(summarizeChunk(fieldGeneration.getPromptKey(), contextFile, chunk, baseHeader, safeWindow)
+                    .trim());
+            log.info("  mapReduce chunk " + index + "/" + chunks.size() + " summarized (" + chunk.length() + " chars)");
+        }
+        return reducePartials(
+                fieldGeneration.getPromptKey(), contextFile, baseHeader, partials, sourceBudget, safeWindow);
+    }
+
+    /**
+     * Combines per-chunk partial summaries into one body via a <strong>hierarchical</strong> reduce:
+     * partials are packed into batches that fit the window (each batch at most {@link #MAX_REDUCE_FANIN}
+     * partials), every batch is summarized, and the process repeats on the batch summaries until a single
+     * summary remains. This avoids the single-reduce trap where hundreds of partials overflow one call
+     * and the file's tail is silently trimmed away, so {@code maxChunks <= 0} (whole-file) coverage
+     * actually reaches the final summary.
+     *
+     * @param promptKey   the prompt template key (shared by map and reduce)
+     * @param contextFile the source file path
+     * @param baseHeader  the header passed through to each request
+     * @param partials    the per-chunk partial summaries (already trimmed); may be empty
+     * @param sourceBudget the source-character budget used to pack a reduce batch
+     * @param safeWindow  the per-call window budget passed to each reduce generation
+     * @return the single combined summary, or an empty string when there are no partials
+     * @throws IOException if the provider throws during generation
+     */
+    private String reducePartials(
+            final String promptKey,
+            final Path contextFile,
+            final AiMdHeader baseHeader,
+            final List<String> partials,
+            final int sourceBudget,
+            final int safeWindow)
+            throws IOException {
+        if (partials.isEmpty()) {
+            return "";
+        }
+        List<String> level = partials;
+        int round = 0;
+        while (level.size() > 1) {
+            round++;
+            final List<String> next = new ArrayList<>(level.size());
+            int i = 0;
+            while (i < level.size()) {
+                final StringBuilder batch = new StringBuilder();
+                int inBatch = 0;
+                while (inBatch < MAX_REDUCE_FANIN
+                        && i < level.size()
+                        && (inBatch == 0
+                                || batch.length() + level.get(i).length() + REDUCE_LABEL_OVERHEAD_CHARS
+                                        <= sourceBudget)) {
+                    batch.append(REDUCE_PART_LABEL)
+                            .append(inBatch + 1)
+                            .append(":\n")
+                            .append(level.get(i))
+                            .append("\n\n");
+                    inBatch++;
+                    i++;
+                }
+                next.add(summarizeChunk(promptKey, contextFile, batch.toString(), baseHeader, safeWindow)
+                        .trim());
+            }
+            log.info("  mapReduce reduce round " + round + ": " + level.size() + " -> " + next.size() + " partial(s)");
+            if (next.size() >= level.size()) {
+                // Pathological: partials too large to combine two-at-a-time. Collapse to one trimmed reduce
+                // so the method always terminates rather than looping without shrinking.
+                final StringBuilder all = new StringBuilder();
+                int n = 0;
+                for (final String partial : level) {
+                    all.append(REDUCE_PART_LABEL)
+                            .append(++n)
+                            .append(":\n")
+                            .append(partial)
+                            .append("\n\n");
+                }
+                return summarizeChunk(promptKey, contextFile, all.toString(), baseHeader, safeWindow)
+                        .trim();
+            }
+            level = next;
+        }
+        return level.get(0);
+    }
+
+    /**
+     * Prepares the prompt for one chunk (trimming to the window) and returns the provider's summary.
+     *
+     * @param promptKey              the prompt template key
+     * @param contextFile            the source file path
+     * @param chunk                  the chunk (or concatenated partials) to summarize
+     * @param baseHeader             the header passed through to the request
+     * @param effectiveMaxInputChars the per-call window budget
+     * @return the provider's summary for the chunk
+     * @throws IOException if the provider throws during generation
+     */
+    private String summarizeChunk(
+            final String promptKey,
+            final Path contextFile,
+            final String chunk,
+            final AiMdHeader baseHeader,
+            final int effectiveMaxInputChars)
+            throws IOException {
+        return generateWithOverflowRetry(promptKey, contextFile, chunk, baseHeader, effectiveMaxInputChars);
+    }
+
+    /**
+     * Trims {@code source} to {@code window} and generates, retrying with a progressively smaller window
+     * (up to {@link #MAX_OVERFLOW_RETRIES}) when the provider rejects the prompt for exceeding the model's
+     * context. This is the char-estimate safety net: a token-dense prompt can exceed the context even
+     * after the char-based trim, so rather than fail the build we re-trim and retry. Any non-overflow
+     * exception propagates immediately.
+     *
+     * @param promptKey   the prompt template key
+     * @param contextFile the source file path
+     * @param source      the source text to trim and summarize
+     * @param baseHeader  the header passed through to the request
+     * @param window      the initial per-call window budget (characters)
+     * @return the provider's generated text
+     * @throws IOException if the provider throws an {@link IOException} during generation
+     */
+    private String generateWithOverflowRetry(
+            final String promptKey,
+            final Path contextFile,
+            final String source,
+            final AiMdHeader baseHeader,
+            final int window)
+            throws IOException {
+        int budget = window;
+        for (int attempt = 0; ; attempt++) {
+            final AiPreparedPrompt prepared = promptPreparationSupport.preparePrompt(
+                    new AiGenerationRequest(promptKey, contextFile, source, baseHeader), budget);
+            try {
+                return generationProvider.generate(
+                        new AiGenerationRequest(promptKey, contextFile, prepared.sourceText(), baseHeader));
+            } catch (final RuntimeException e) {
+                final int reduced = Math.max(MIN_CHUNK_CHARS, budget * OVERFLOW_RETRY_BACKOFF_PERCENT / PERCENT);
+                // Rethrow (giving up) once the retries are exhausted, when the window is already at the
+                // floor (shrinking further would not help), or on a non-overflow error. The cheap
+                // comparisons are checked before the cause-chain walk of isContextOverflow(e).
+                if (attempt >= MAX_OVERFLOW_RETRIES || reduced >= budget || !isContextOverflow(e)) {
+                    throw e;
+                }
+                log.warn("AI provider rejected the prompt (context overflow) for " + contextFile
+                        + "; retrying with a smaller window (" + budget + " -> " + reduced + " chars)");
+                budget = reduced;
+            }
+        }
+    }
+
+    /**
+     * Returns whether {@code error} (or any cause in its chain) is a model context-overflow, matched on
+     * the provider's message ({@link #CONTEXT_OVERFLOW_MARKER}).
+     *
+     * @param error the thrown error
+     * @return {@code true} when the error indicates the prompt exceeded the context window
+     */
+    private static boolean isContextOverflow(final Throwable error) {
+        for (Throwable cause = error; cause != null; cause = cause.getCause()) {
+            final String message = cause.getMessage();
+            if (message != null && message.contains(CONTEXT_OVERFLOW_MARKER)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Estimates one generation's seconds for the given char count, using the model's {@code <calibration>}
+     * (measured per-machine throughput) when present, otherwise the estimator's built-in model. Mirrors
+     * {@code SourceFileIndexer}'s plan-time estimate so the live per-file ETA agrees with the plan.
+     *
+     * @param sourceChars the processed source character count
+     * @param config      the model's generation config (may carry a calibration)
+     * @return the estimated seconds
+     */
+    private long estimateSeconds(final int sourceChars, final AiGenerationConfig config) {
+        final AiCalibration calibration = config.getCalibration();
+        if (calibration == null) {
+            return timeEstimator.estimateSeconds(sourceChars);
+        }
+        return timeEstimator.estimateSecondsCalibrated(
+                sourceChars,
+                calibration.getPrefillTokensPerSecond(),
+                calibration.getDecodeTokensPerSecond(),
+                calibration.getCharsPerToken());
+    }
+
+    /**
+     * Returns a short display name for a context file (its file name, or the full path as a fallback).
+     *
+     * @param contextFile the file path
+     * @return the display name
+     */
+    private static String contextName(final Path contextFile) {
+        final Path fileName = contextFile.getFileName();
+        return fileName != null ? fileName.toString() : contextFile.toString();
+    }
+
     /**
      * Returns the effective {@code maxInputChars} for the given field generation entry.
      *
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiIndexPlan.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiIndexPlan.java
index c0f56b2..1d1b7c0 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiIndexPlan.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiIndexPlan.java
@@ -9,6 +9,7 @@
 import java.util.List;
 import java.util.Map;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy;
 import net.ladenthin.maven.llamacpp.aiindex.support.AiGenerationTimeEstimator;
 
 /**
@@ -247,6 +248,36 @@ public int windowExceededCount() {
         return total;
     }
 
+    /**
+     * Returns the number of over-window files whose rule's {@code onOversize} strategy is
+     * {@link AiOversizeStrategy#FAIL} — i.e. the ones that abort the build. Over-window files with a
+     * {@code sample}/{@code mapReduce}/{@code deterministic} strategy are handled at run time and do not
+     * count here.
+     *
+     * @return the count of over-window files that fail the build
+     */
+    public int windowFailCount() {
+        int total = 0;
+        for (final List<Entry> entries : routesByModel.values()) {
+            for (final Entry entry : entries) {
+                if (entry.exceedsWindow() && strategyOf(entry) == AiOversizeStrategy.FAIL) {
+                    total++;
+                }
+            }
+        }
+        return total;
+    }
+
+    /**
+     * Returns the oversize strategy configured on an entry's rule.
+     *
+     * @param entry the plan entry
+     * @return the parsed oversize strategy
+     */
+    private static AiOversizeStrategy strategyOf(final Entry entry) {
+        return entry.rule().getOversizeStrategy();
+    }
+
     /**
      * Returns the summed estimated seconds for one model's entries.
      *
@@ -299,7 +330,9 @@ public String renderMarkdown(final Path baseDir) {
                 .append(unmatched.size())
                 .append(" unmatched, ")
                 .append(windowExceededCount())
-                .append(" over window _(time is a rough estimate)_\n");
+                .append(" over window (")
+                .append(windowFailCount())
+                .append(" will fail) _(time is a rough estimate)_\n");
         for (final Map.Entry<String, List<Entry>> group : routesByModel.entrySet()) {
             final List<Entry> entries = group.getValue();
             sb.append("\n### Model `")
@@ -360,6 +393,7 @@ private void appendWindowExceededSection(final StringBuilder sb, final Path base
         for (final Map.Entry<String, List<Entry>> group : routesByModel.entrySet()) {
             for (final Entry entry : group.getValue()) {
                 if (entry.exceedsWindow()) {
+                    final AiOversizeStrategy strategy = strategyOf(entry);
                     sb.append("- ")
                             .append(relativize(baseDir, entry.file()))
                             .append(" -> model `")
@@ -368,13 +402,18 @@ private void appendWindowExceededSection(final StringBuilder sb, final Path base
                             .append(entry.sourceChars())
                             .append(" chars > window ")
                             .append(entry.availableSourceChars())
-                            .append(" chars)\n");
+                            .append(" chars) onOversize=")
+                            .append(strategy.configValue())
+                            .append(strategy == AiOversizeStrategy.FAIL ? " -> FAILS BUILD" : " -> handled")
+                            .append('\n');
                 }
             }
         }
-        sb.append("\nThis fails the build. Add a <fieldGeneration> rule with a size <condition> that routes")
-                .append(" these files to a model with a large enough context window (config only; the build")
-                .append(" never picks a model for you).\n");
+        if (windowFailCount() > 0) {
+            sb.append("\nThe onOversize=fail entries fail the build. Either route them to a model with a large")
+                    .append(" enough context window, or set onOversize on the rule (sample/mapReduce/deterministic)")
+                    .append(" to handle oversized files (config only; the build never picks a model for you).\n");
+        }
     }
 
     /**
@@ -389,7 +428,8 @@ private String windowCell(final Entry entry) {
             return "-";
         }
         if (entry.exceedsWindow()) {
-            return "(!) " + entry.sourceChars() + ">" + entry.availableSourceChars();
+            return "(!) " + entry.sourceChars() + ">" + entry.availableSourceChars() + " "
+                    + strategyOf(entry).configValue();
         }
         return "ok";
     }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/SourceFileIndexer.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/SourceFileIndexer.java
index 8067f52..cf9ee03 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/SourceFileIndexer.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/indexer/SourceFileIndexer.java
@@ -12,6 +12,7 @@
 import java.util.List;
 import java.util.stream.Stream;
 import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiCalibration;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiCondition;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiConditionEvaluator;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
@@ -19,6 +20,7 @@
 import net.ladenthin.maven.llamacpp.aiindex.config.AiFileContext;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiOversizeStrategy;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationResult;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdDocument;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdDocumentCodec;
@@ -222,27 +224,82 @@ public AiIndexPlan classify(
                 plan.addUnmatched(file);
             } else if (rule.isSkip()) {
                 plan.addSkipped(file);
+            } else if (modelDefinitionSupport != null && promptPreparationSupport != null) {
+                final AiGenerationConfig modelConfig = modelDefinitionSupport.getConfig(rule.getAiDefinitionKey());
+                final int basePromptLength = promptPreparationSupport.getBasePromptLength(rule.getPromptKey(), file);
+                final long availableSourceChars =
+                        AiInputWindowCalculator.availableSourceChars(modelConfig, basePromptLength);
+                final long sourceChars = compatibilityHelper.readString(file).length();
+                final long routeSeconds =
+                        estimateRouteSeconds(rule, modelConfig, fileSizeBytes, sourceChars, availableSourceChars);
+                plan.addRoute(rule.getAiDefinitionKey(), file, rule, routeSeconds, sourceChars, availableSourceChars);
             } else {
                 final long estimatedSeconds =
                         timeEstimator.estimateSeconds((int) Math.min(fileSizeBytes, Integer.MAX_VALUE));
-                if (modelDefinitionSupport != null && promptPreparationSupport != null) {
-                    final AiGenerationConfig modelConfig = modelDefinitionSupport.getConfig(rule.getAiDefinitionKey());
-                    final int basePromptLength =
-                            promptPreparationSupport.getBasePromptLength(rule.getPromptKey(), file);
-                    final long availableSourceChars =
-                            AiInputWindowCalculator.availableSourceChars(modelConfig, basePromptLength);
-                    final long sourceChars =
-                            compatibilityHelper.readString(file).length();
-                    plan.addRoute(
-                            rule.getAiDefinitionKey(), file, rule, estimatedSeconds, sourceChars, availableSourceChars);
-                } else {
-                    plan.addRoute(rule.getAiDefinitionKey(), file, rule, estimatedSeconds);
-                }
+                plan.addRoute(rule.getAiDefinitionKey(), file, rule, estimatedSeconds);
             }
         }
         return plan;
     }
 
+    /**
+     * Estimates the generation time for one routed file, accounting for the rule's oversize strategy so
+     * the plan ETA stays realistic for huge files (the per-call cost is bounded by the model window, not
+     * the raw file size). A file that fits the window uses the normal size-based estimate; an over-window
+     * file is estimated per strategy: {@code deterministic} is free, {@code sample}/{@code fail} cost one
+     * window pass, and {@code mapReduce} costs (chunks + reduce) window passes (capped by {@code maxChunks}).
+     *
+     * @param rule                 the routing rule
+     * @param modelConfig          the routed model's config (its {@code <calibration>} is used when present)
+     * @param fileSizeBytes        the file size in bytes
+     * @param sourceChars          the source length in characters
+     * @param availableSourceChars the per-call source-character budget of the routed model+prompt
+     * @return the estimated seconds
+     */
+    private long estimateRouteSeconds(
+            final AiFieldGenerationConfig rule,
+            final AiGenerationConfig modelConfig,
+            final long fileSizeBytes,
+            final long sourceChars,
+            final long availableSourceChars) {
+        if (sourceChars <= availableSourceChars) {
+            return estimateSeconds(fileSizeBytes, modelConfig);
+        }
+        final long windowSeconds = estimateSeconds(availableSourceChars, modelConfig);
+        final AiOversizeStrategy strategy = rule.getOversizeStrategy();
+        if (strategy == AiOversizeStrategy.DETERMINISTIC) {
+            return 0L;
+        }
+        if (strategy == AiOversizeStrategy.MAP_REDUCE) {
+            final long denom = Math.max(1L, availableSourceChars);
+            final long naturalChunks = Math.max(1L, (sourceChars + denom - 1) / denom);
+            final long chunks = rule.getMaxChunks() > 0 ? Math.min(rule.getMaxChunks(), naturalChunks) : naturalChunks;
+            return (chunks + 1) * windowSeconds;
+        }
+        return windowSeconds;
+    }
+
+    /**
+     * Estimates one generation's seconds for the given char count, using the model's {@code <calibration>}
+     * (measured per-machine throughput) when present and valid, otherwise the estimator's built-in model.
+     *
+     * @param chars       the character count to estimate for
+     * @param modelConfig the routed model's config (may carry a calibration)
+     * @return the estimated seconds
+     */
+    private long estimateSeconds(final long chars, final AiGenerationConfig modelConfig) {
+        final int cappedChars = (int) Math.min(chars, Integer.MAX_VALUE);
+        final AiCalibration calibration = modelConfig.getCalibration();
+        if (calibration == null) {
+            return timeEstimator.estimateSeconds(cappedChars);
+        }
+        return timeEstimator.estimateSecondsCalibrated(
+                cappedChars,
+                calibration.getPrefillTokensPerSecond(),
+                calibration.getDecodeTokensPerSecond(),
+                calibration.getCharsPerToken());
+    }
+
     /**
      * Writes the {@code .ai.md} for one source file using the given rule and a provider-bearing
      * support. Honours the incremental-skip rule: an up-to-date target (matching source checksum, no
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/CalibrateMojo.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/CalibrateMojo.java
new file mode 100644
index 0000000..fdbc8ee
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/CalibrateMojo.java
@@ -0,0 +1,192 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.mojo;
+
+import java.io.IOException;
+import java.util.LinkedHashMap;
+import java.util.Locale;
+import java.util.Map;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
+import net.ladenthin.maven.llamacpp.aiindex.indexer.AiCalibrationMeasurement;
+import net.ladenthin.maven.llamacpp.aiindex.indexer.AiCalibrationRunner;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProviderFactory;
+import org.apache.maven.plugin.MojoExecutionException;
+import org.apache.maven.plugins.annotations.Mojo;
+import org.apache.maven.plugins.annotations.Parameter;
+
+/**
+ * Maven goal {@code ai-index:calibrate}: a preflight + timing pass that sits between {@code planOnly} (no
+ * model loaded) and a real {@code generate} run.
+ *
+ * <p>For each distinct model a run would load (the {@code aiDefinitionKey}s referenced by
+ * {@code <fieldGenerations>}) it loads the model once (catching a bad path / OOM / wrong native early),
+ * runs a couple of representative generations, reads the model's own measured prefill/decode throughput,
+ * and prints a paste-ready {@code <calibration>} block. Paste that onto the matching {@code <aiDefinition>}
+ * so the plan's time estimate reflects <em>this</em> machine instead of the built-in reference-CPU
+ * coefficients. The numbers are per machine (GPU/CPU, quant, context), so re-run on each host.</p>
+ */
+@SuppressWarnings("initialization.fields.uninitialized")
+@Mojo(name = "calibrate", threadSafe = true)
+public class CalibrateMojo extends AbstractAiIndexMojo {
+
+    /** Creates a new {@link CalibrateMojo}. */
+    public CalibrateMojo() {
+        // no-op
+    }
+
+    /** llama.cpp context window size (unused by calibrate, which uses each model's own config). */
+    @Parameter(property = "aiIndex.llama.contextSize", defaultValue = "2048")
+    private int llamaContextSize;
+
+    /** CPU threads (unused by calibrate, which uses each model's own config). */
+    @Parameter(property = "aiIndex.llama.threads", defaultValue = "2")
+    private int llamaThreads;
+
+    private final AiCalibrationRunner calibrationRunner = new AiCalibrationRunner();
+
+    @Override
+    protected int getLlamaContextSize() {
+        return llamaContextSize;
+    }
+
+    @Override
+    protected int getLlamaThreads() {
+        return llamaThreads;
+    }
+
+    @Override
+    protected boolean isPhaseSkipped() {
+        // calibrate is a manual diagnostic goal, not one of the file/package/project phases; only the
+        // global aiIndex.skip disables it.
+        return false;
+    }
+
+    @Override
+    public void execute() throws MojoExecutionException {
+        if (shouldSkip()) {
+            getLog().info("AI index calibration skipped.");
+            return;
+        }
+        if (fieldGenerations == null || fieldGenerations.isEmpty()) {
+            throw new MojoExecutionException("No <fieldGenerations> configured; nothing to calibrate.");
+        }
+
+        final AiPromptSupport promptSupport = buildPromptSupport();
+        final AiModelDefinitionSupport modelDefinitionSupport = buildAiModelDefinitionSupport();
+        final AiPromptPreparationSupport promptPreparationSupport = new AiPromptPreparationSupport(promptSupport);
+        final AiGenerationProviderFactory providerFactory = new AiGenerationProviderFactory();
+
+        // Distinct routed models, each mapped to a representative prompt key (skip rules have none).
+        final Map<String, String> modelToPrompt = new LinkedHashMap<>();
+        for (final AiFieldGenerationConfig rule : fieldGenerations) {
+            if (rule == null || rule.getAiDefinitionKey() == null || rule.getPromptKey() == null) {
+                continue;
+            }
+            modelToPrompt.putIfAbsent(rule.getAiDefinitionKey(), rule.getPromptKey());
+        }
+        if (modelToPrompt.isEmpty()) {
+            throw new MojoExecutionException("No routable (model + prompt) rule found to calibrate.");
+        }
+
+        getLog().info("AI index calibration: " + modelToPrompt.size() + " model(s). Provider: " + generationProvider);
+        final StringBuilder pasteBlocks = new StringBuilder();
+        for (final Map.Entry<String, String> entry : modelToPrompt.entrySet()) {
+            calibrateModel(
+                    entry.getKey(),
+                    entry.getValue(),
+                    modelDefinitionSupport,
+                    promptSupport,
+                    promptPreparationSupport,
+                    providerFactory,
+                    pasteBlocks);
+        }
+
+        getLog().info("");
+        getLog().info("Paste each <calibration> onto its matching <aiDefinition> (numbers are per machine).");
+        getLog().info("These are the model's own measured prefill/decode throughput (from the engine's "
+                + "per-call timings); only the mock/no-timings path falls back to a wall-clock estimate.");
+        for (final String line : pasteBlocks.toString().split("\n", -1)) {
+            getLog().info(line);
+        }
+    }
+
+    /**
+     * Loads one model, measures it via {@link AiCalibrationRunner}, logs the result, and appends a
+     * paste-ready {@code <calibration>} block for it.
+     *
+     * @param modelKey                 the aiDefinitionKey to calibrate
+     * @param promptKey                a representative prompt key routed to this model
+     * @param modelDefinitionSupport   model lookup
+     * @param promptSupport            prompt lookup (for the provider)
+     * @param promptPreparationSupport prompt preparation (for the window calculation)
+     * @param providerFactory          provider factory
+     * @param pasteBlocks              accumulator for the printable {@code <calibration>} blocks
+     * @throws MojoExecutionException if the model fails to load or generate
+     */
+    private void calibrateModel(
+            final String modelKey,
+            final String promptKey,
+            final AiModelDefinitionSupport modelDefinitionSupport,
+            final AiPromptSupport promptSupport,
+            final AiPromptPreparationSupport promptPreparationSupport,
+            final AiGenerationProviderFactory providerFactory,
+            final StringBuilder pasteBlocks)
+            throws MojoExecutionException {
+        final AiGenerationConfig config = modelDefinitionSupport.getConfig(modelKey);
+        final long windowChars = calibrationRunner.windowChars(config, promptKey, promptPreparationSupport);
+
+        getLog().info("");
+        getLog().info("Model '" + modelKey + "': loading (window ~" + windowChars + " source chars)...");
+        try (AiGenerationProvider provider =
+                providerFactory.create(generationProvider, buildLlamaCppJniConfig(modelKey), promptSupport)) {
+            final AiCalibrationMeasurement m =
+                    calibrationRunner.measure(provider, config, promptKey, promptPreparationSupport);
+
+            getLog().info(String.format(
+                    Locale.ROOT,
+                    "Model '%s': loaded+first-gen ~%.1fs | prefill %.0f tok/s | decode %.0f tok/s | ~%.2f chars/token",
+                    modelKey,
+                    m.loadSeconds(),
+                    m.prefillTokensPerSecond(),
+                    m.decodeTokensPerSecond(),
+                    m.charsPerToken()));
+            if (m.prefillTokensPerSecond() > 0 && m.midPrefillTokensPerSecond() > 0) {
+                getLog().info(String.format(
+                        Locale.ROOT,
+                        "  (mid-window prefill %.0f tok/s vs near-window %.0f tok/s - larger gap => more curvature)",
+                        m.midPrefillTokensPerSecond(),
+                        m.prefillTokensPerSecond()));
+            }
+            appendPasteBlock(pasteBlocks, modelKey, m);
+        } catch (final IOException e) {
+            throw new MojoExecutionException("Calibration failed for model '" + modelKey + "': " + e.getMessage(), e);
+        }
+    }
+
+    /**
+     * Appends a copy-pasteable {@code <calibration>} block (with a comment naming the model) to the buffer.
+     *
+     * @param out      the buffer
+     * @param modelKey the model key (for the comment)
+     * @param m        the measurement
+     */
+    private static void appendPasteBlock(
+            final StringBuilder out, final String modelKey, final AiCalibrationMeasurement m) {
+        out.append("<!-- calibration for aiDefinition '").append(modelKey).append("' (this machine) -->\n");
+        out.append("<calibration>\n");
+        out.append(String.format(
+                Locale.ROOT,
+                "    <prefillTokensPerSecond>%.1f</prefillTokensPerSecond>%n",
+                m.prefillTokensPerSecond()));
+        out.append(String.format(
+                Locale.ROOT, "    <decodeTokensPerSecond>%.1f</decodeTokensPerSecond>%n", m.decodeTokensPerSecond()));
+        out.append(String.format(Locale.ROOT, "    <charsPerToken>%.2f</charsPerToken>%n", m.charsPerToken()));
+        out.append("</calibration>\n");
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/GenerateMojo.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/GenerateMojo.java
index e00bbab..8a38555 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/GenerateMojo.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/mojo/GenerateMojo.java
@@ -9,6 +9,8 @@
 import java.util.List;
 import java.util.Map;
 import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinition;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinitionSupport;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationSelector;
 import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
 import net.ladenthin.maven.llamacpp.aiindex.indexer.AiFieldGenerationSupport;
@@ -78,6 +80,16 @@ public GenerateMojo() {
     @Parameter(property = "aiIndex.excludes")
     private List<String> excludes;
 
+    /**
+     * Reusable, named {@code <factDefinitions>} groups referenced from a rule's {@code <factsKey>}, so a
+     * fact set (e.g. {@code java-facts}, {@code sql-facts}) is defined once and shared across rules
+     * instead of repeated inline. Resolved onto each rule's {@code facts} before indexing.
+     *
+     * @see net.ladenthin.maven.llamacpp.aiindex.config.AiFactDefinitionSupport
+     */
+    @Parameter
+    private List<AiFactDefinition> factDefinitions;
+
     /**
      * Exclusive lower file-size bound in bytes: source files whose size is {@code <= this} are skipped.
      * {@code 0} (default) disables the lower bound. Together with {@link #maxFileSizeBytes} this lets one
@@ -152,6 +164,10 @@ public void execute() throws MojoExecutionException {
         final AiPromptSupport promptSupport = buildPromptSupport();
         final AiModelDefinitionSupport modelDefinitionSupport = buildAiModelDefinitionSupport();
         final AiPromptPreparationSupport promptPreparationSupport = new AiPromptPreparationSupport(promptSupport);
+        // Resolve each rule's factsKey to its shared factDefinitions group (copies the counters onto the
+        // rule's facts) BEFORE validation, so the resolved fact patterns are validated too.
+        resolveSharedFacts();
+
         final AiFieldGenerationSelector selector = new AiFieldGenerationSelector();
         // Fail fast on a bad rule set (e.g. >1 fallback, a route rule missing prompt/model).
         selector.validate(fieldGenerations);
@@ -196,19 +212,18 @@ public void execute() throws MojoExecutionException {
                         + "add a <fallback> rule or a matching rule (see the plan above).");
             }
 
-            // 3b. A file larger than its routed model's window would lose content if trimmed. This is
-            //     ALWAYS a hard failure (planOnly and real run alike). The fix is user configuration,
-            //     never an automatic model choice: the user must add a routing rule (<fieldGeneration>
-            //     with a size <condition>) that sends oversized files to a model with a large enough
-            //     context window. The plugin deliberately does not pick a model for you.
-            final int overWindowCount = plan.windowExceededCount();
-            if (overWindowCount > 0) {
-                throw new MojoExecutionException(overWindowCount
-                        + " source file(s) exceed their routed model's context window (see the 'Over window' "
-                        + "section in the plan above). Add a <fieldGeneration> rule with a size <condition> "
-                        + "that routes these files to a model with a large enough context window (see the "
-                        + "big-window fallback example in the POM). The build does not pick a model for you; "
-                        + "this is configuration only.");
+            // 3b. A file larger than its routed model's window would lose content if trimmed. By default
+            //     (onOversize=fail) this is a hard failure: the fix is user configuration, never an
+            //     automatic model choice — route oversized files to a larger-context model, or set the
+            //     rule's onOversize (sample/mapReduce/deterministic) to handle them at run time. Only the
+            //     fail entries abort here; the handled ones are processed during generation.
+            final int overWindowFailCount = plan.windowFailCount();
+            if (overWindowFailCount > 0) {
+                throw new MojoExecutionException(overWindowFailCount
+                        + " source file(s) exceed their routed model's context window with onOversize=fail "
+                        + "(see the 'Over window' section in the plan above). Route them to a model with a "
+                        + "large enough context window, or set onOversize=sample|mapReduce|deterministic on "
+                        + "the rule. The build does not pick a model for you; this is configuration only.");
             }
 
             if (planOnly) {
@@ -276,4 +291,19 @@ private List<String> resolveFileExtensions() {
         }
         return configured;
     }
+
+    /**
+     * Resolves each rule's {@code factsKey} to its shared {@code <factDefinitions>} group, copying the
+     * counters onto the rule's {@code facts}. Translates a misconfiguration (unknown key, or a definition
+     * with a null key) into a {@link MojoExecutionException} so Maven reports a user configuration error.
+     *
+     * @throws MojoExecutionException if a {@code factsKey} matches no group or a definition has a null key
+     */
+    private void resolveSharedFacts() throws MojoExecutionException {
+        try {
+            new AiFactDefinitionSupport(factDefinitions).resolveFactsKeys(fieldGenerations);
+        } catch (final IllegalArgumentException | NullPointerException e) {
+            throw new MojoExecutionException("Invalid factDefinitions/factsKey configuration: " + e.getMessage(), e);
+        }
+    }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java
index 262de49..3699410 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProvider.java
@@ -21,6 +21,19 @@ public interface AiGenerationProvider extends AutoCloseable {
      */
     String generate(AiGenerationRequest request) throws IOException;
 
+    /**
+     * Generates text and returns it together with the model's measured timing, for the
+     * {@code ai-index:calibrate} goal. The default implementation delegates to {@link #generate} and
+     * reports no timings (rates {@code 0}); providers that expose timings override this.
+     *
+     * @param request the generation request
+     * @return the generated text plus timing (rates {@code 0} when unavailable)
+     * @throws IOException if the underlying provider fails
+     */
+    default AiGenerationTimings generateWithTimings(final AiGenerationRequest request) throws IOException {
+        return new AiGenerationTimings(generate(request), 0, 0.0d, 0, 0.0d);
+    }
+
     @Override
     default void close() throws IOException {}
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java
new file mode 100644
index 0000000..f493442
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimings.java
@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.provider;
+
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+import net.ladenthin.maven.llamacpp.aiindex.support.ConvertToRecord;
+
+/**
+ * A generated text plus the model's measured timing for that generation, used by the
+ * {@code ai-index:calibrate} goal to derive per-machine throughput. Prefill = prompt processing; decode =
+ * answer generation. Rates of {@code 0} mean the provider did not report timings (e.g. the mock provider
+ * or a binding that omits them).
+ *
+ * <p>Record-shaped value type marked {@link ConvertToRecord} for the future Java&nbsp;17+ migration; the
+ * accessors follow record style ({@code text()}, not {@code getText()}).</p>
+ */
+@ConvertToRecord
+@ToString
+@EqualsAndHashCode
+public final class AiGenerationTimings {
+
+    private final String text;
+    private final int promptTokens;
+    private final double prefillTokensPerSecond;
+    private final int predictedTokens;
+    private final double decodeTokensPerSecond;
+
+    /**
+     * Creates a new {@link AiGenerationTimings}.
+     *
+     * @param text                   the generated (parsed) text
+     * @param promptTokens           number of prompt tokens the model processed (prefill)
+     * @param prefillTokensPerSecond measured prefill throughput (tokens/second)
+     * @param predictedTokens        number of tokens the model generated (decode)
+     * @param decodeTokensPerSecond  measured decode throughput (tokens/second)
+     */
+    public AiGenerationTimings(
+            final String text,
+            final int promptTokens,
+            final double prefillTokensPerSecond,
+            final int predictedTokens,
+            final double decodeTokensPerSecond) {
+        this.text = text;
+        this.promptTokens = promptTokens;
+        this.prefillTokensPerSecond = prefillTokensPerSecond;
+        this.predictedTokens = predictedTokens;
+        this.decodeTokensPerSecond = decodeTokensPerSecond;
+    }
+
+    /**
+     * Returns the generated (parsed) text.
+     *
+     * @return the text
+     */
+    public String text() {
+        return text;
+    }
+
+    /**
+     * Returns the number of prompt tokens the model processed.
+     *
+     * @return the prompt token count
+     */
+    public int promptTokens() {
+        return promptTokens;
+    }
+
+    /**
+     * Returns the measured prefill throughput (tokens/second).
+     *
+     * @return the prefill tokens per second
+     */
+    public double prefillTokensPerSecond() {
+        return prefillTokensPerSecond;
+    }
+
+    /**
+     * Returns the number of tokens the model generated.
+     *
+     * @return the predicted token count
+     */
+    public int predictedTokens() {
+        return predictedTokens;
+    }
+
+    /**
+     * Returns the measured decode throughput (tokens/second).
+     *
+     * @return the decode tokens per second
+     */
+    public double decodeTokensPerSecond() {
+        return decodeTokensPerSecond;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java
index 8df8580..ea0aa5a 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProvider.java
@@ -12,9 +12,12 @@
 import lombok.ToString;
 import net.ladenthin.llama.LlamaModel;
 import net.ladenthin.llama.args.ReasoningFormat;
+import net.ladenthin.llama.json.ChatResponseParser;
 import net.ladenthin.llama.parameters.InferenceParameters;
 import net.ladenthin.llama.parameters.ModelParameters;
+import net.ladenthin.llama.value.ChatResponse;
 import net.ladenthin.llama.value.Pair;
+import net.ladenthin.llama.value.Timings;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
 import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport;
 import net.ladenthin.maven.llamacpp.aiindex.support.Java8CompatibilityHelper;
@@ -45,6 +48,7 @@ public final class LlamaCppJniAiGenerationProvider implements AiGenerationProvid
 
     private final AiPromptSupport promptSupport;
     private final AiCompletionParser completionParser = new AiCompletionParser();
+    private final ChatResponseParser chatResponseParser = new ChatResponseParser();
     private final Java8CompatibilityHelper compatibilityHelper = new Java8CompatibilityHelper();
 
     /**
@@ -128,6 +132,42 @@ private LlamaModel model() {
 
     @Override
     public String generate(final AiGenerationRequest request) throws IOException {
+        return completionParser.parseCompletion(model().chatCompleteText(buildInferenceParameters(request)));
+    }
+
+    // Narrows away the interface's checked IOException: the chat path (chatComplete + parse) throws only
+    // unchecked exceptions, so declaring IOException here would be bogus (BED).
+    @Override
+    public AiGenerationTimings generateWithTimings(final AiGenerationRequest request) {
+        // chatComplete(...) returns the full OpenAI-compatible JSON, which the server populates with a
+        // "timings" object (prompt_n / predicted_n / prompt_per_second / predicted_per_second) for every
+        // real generation. chatCompleteText(...) discards it; here we parse it into a ChatResponse and
+        // surface the model's OWN measured throughput (no chars/token estimate).
+        final ChatResponse response =
+                chatResponseParser.parseResponse(model().chatComplete(buildInferenceParameters(request)));
+        final String text = response.getChoices().isEmpty()
+                ? ""
+                : response.getChoices().get(0).getMessage().getContent();
+        final Timings timings = response.getTimings();
+        if (timings == null) {
+            // A build/response without timings degrades to zero rates so the caller's fallback can act.
+            return new AiGenerationTimings(text, 0, 0.0d, 0, 0.0d);
+        }
+        return new AiGenerationTimings(
+                text,
+                (int) timings.getPromptN(),
+                timings.getPromptPerSecond(),
+                (int) timings.getPredictedN(),
+                timings.getPredictedPerSecond());
+    }
+
+    /**
+     * Builds the immutable {@link InferenceParameters} for the given request from the resolved config.
+     *
+     * @param request the generation request
+     * @return the inference parameters
+     */
+    private InferenceParameters buildInferenceParameters(final AiGenerationRequest request) {
         // Static instructions go in the SYSTEM message (byte-identical across files, so its KV
         // prefix is reused by cache_prompt); the variable file name + source go in the USER message.
         final String systemPrompt = promptSupport.systemPrompt(request.promptKey());
@@ -166,13 +206,10 @@ public String generate(final AiGenerationRequest request) throws IOException {
 
         // Only override the DRY sequence breakers when explicitly configured; an empty list keeps
         // the binding/model default set instead of clearing it.
-        final InferenceParameters inferenceParameters =
-                config.drySequenceBreakers().isEmpty()
-                        ? baseParameters
-                        : baseParameters.withDrySequenceBreakers(
-                                config.drySequenceBreakers().toArray(new String[0]));
-
-        return completionParser.parseCompletion(model().chatCompleteText(inferenceParameters));
+        return config.drySequenceBreakers().isEmpty()
+                ? baseParameters
+                : baseParameters.withDrySequenceBreakers(
+                        config.drySequenceBreakers().toArray(new String[0]));
     }
 
     @Override
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java
index d0207c8..feadf42 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProvider.java
@@ -12,6 +12,18 @@
 @ToString
 public class MockAiGenerationProvider implements AiGenerationProvider {
 
+    /** Synthetic prefill throughput reported by the mock, so calibrate runs deterministically without a model. */
+    private static final double MOCK_PREFILL_TOKENS_PER_SECOND = 1000.0d;
+
+    /** Synthetic decode throughput reported by the mock. */
+    private static final double MOCK_DECODE_TOKENS_PER_SECOND = 100.0d;
+
+    /** Synthetic characters per token used to derive the mock prompt-token count from the source length. */
+    private static final int MOCK_CHARS_PER_TOKEN = 4;
+
+    /** Synthetic decode token count reported by the mock. */
+    private static final int MOCK_PREDICTED_TOKENS = 64;
+
     /** Creates a new {@link MockAiGenerationProvider}. */
     public MockAiGenerationProvider() {
         // no-op
@@ -24,4 +36,15 @@ public String generate(final AiGenerationRequest request) throws IOException {
         final String fileName = fileNamePath != null ? fileNamePath.toString() : file.toString();
         return "Mock summary for " + fileName;
     }
+
+    @Override
+    public AiGenerationTimings generateWithTimings(final AiGenerationRequest request) throws IOException {
+        final int promptTokens = request.sourceText().length() / MOCK_CHARS_PER_TOKEN;
+        return new AiGenerationTimings(
+                generate(request),
+                promptTokens,
+                MOCK_PREFILL_TOKENS_PER_SECOND,
+                MOCK_PREDICTED_TOKENS,
+                MOCK_DECODE_TOKENS_PER_SECOND);
+    }
 }
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummary.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummary.java
new file mode 100644
index 0000000..aeb4897
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummary.java
@@ -0,0 +1,94 @@
+// @formatter:off
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+// @formatter:on
+package net.ladenthin.maven.llamacpp.aiindex.support;
+
+/**
+ * Builds a model-free, deterministic Markdown body for files too large (or too uninteresting) to feed to
+ * an AI model — e.g. huge repetitive data files. The body states size and line count and shows a head
+ * (and, when the file is long enough, a tail) sample, so the index still carries a useful, instant,
+ * zero-cost description. Pure; no I/O.
+ */
+public final class AiDeterministicSummary {
+
+    /** Newline used to split and count lines. */
+    private static final char NEWLINE = '\n';
+
+    /** Utility class; not instantiable. */
+    private AiDeterministicSummary() {
+        // no-op
+    }
+
+    /**
+     * Builds the deterministic body.
+     *
+     * @param source      the full source text
+     * @param contextName a human-readable name for the source (e.g. the file name)
+     * @param sampleLines number of leading (and, when the file is long, trailing) lines to show; values
+     *                    {@code <= 0} show no sample, only the metadata line
+     * @return the Markdown body
+     */
+    public static String body(final String source, final String contextName, final int sampleLines) {
+        final int chars = source.length();
+        final int lines = countLines(source);
+        final StringBuilder sb = new StringBuilder(256);
+        sb.append("> Large file summarized deterministically (no AI): `")
+                .append(contextName)
+                .append("` - ")
+                .append(chars)
+                .append(" chars, ")
+                .append(lines)
+                .append(" lines.\n");
+        if (sampleLines <= 0 || lines == 0) {
+            return sb.toString();
+        }
+        final String[] all = source.split("\n", -1);
+        if (lines <= sampleLines * 2) {
+            appendFenced(sb, "Content", all, 0, all.length);
+        } else {
+            appendFenced(sb, "First " + sampleLines + " lines", all, 0, sampleLines);
+            appendFenced(sb, "Last " + sampleLines + " lines", all, all.length - sampleLines, all.length);
+        }
+        return sb.toString();
+    }
+
+    /**
+     * Appends a labelled fenced block with {@code lines[from..toExclusive)}.
+     *
+     * @param sb          the buffer
+     * @param label       the section label
+     * @param lines       the split lines
+     * @param from        start index (inclusive)
+     * @param toExclusive end index (exclusive)
+     */
+    private static void appendFenced(
+            final StringBuilder sb, final String label, final String[] lines, final int from, final int toExclusive) {
+        sb.append('\n').append(label).append(":\n```\n");
+        for (int i = from; i < toExclusive; i++) {
+            sb.append(lines[i]).append('\n');
+        }
+        sb.append("```\n");
+    }
+
+    /**
+     * Counts lines: zero for empty input, otherwise the number of newlines plus one when the text does not
+     * end with a newline.
+     *
+     * @param source the text
+     * @return the line count
+     */
+    private static int countLines(final String source) {
+        if (source.isEmpty()) {
+            return 0;
+        }
+        int newlines = 0;
+        for (int i = 0; i < source.length(); i++) {
+            if (source.charAt(i) == NEWLINE) {
+                newlines++;
+            }
+        }
+        return source.charAt(source.length() - 1) == NEWLINE ? newlines : newlines + 1;
+    }
+}
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimator.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimator.java
index 437bee0..96fc6bc 100644
--- a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimator.java
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimator.java
@@ -165,6 +165,60 @@ public long estimateSeconds(final int sourceChars, final int expectedOutputToken
         return Math.round(millis / MILLIS_PER_SECOND * ETA_SAFETY_MARGIN);
     }
 
+    /**
+     * Calibrated estimate assuming {@link #DEFAULT_EXPECTED_OUTPUT_TOKENS} of output. Delegates to
+     * {@link #estimateSecondsCalibrated(int, int, double, double, double)}.
+     *
+     * @param sourceChars             number of source characters that will be sent to the model
+     * @param prefillTokensPerSecond  measured prefill throughput, or {@code <= 0} to fall back
+     * @param decodeTokensPerSecond   measured decode throughput, or {@code <= 0} to fall back
+     * @param calibratedCharsPerToken measured characters per token, or {@code <= 0} to use the default
+     * @return estimated total time in seconds, rounded to the nearest second
+     */
+    public long estimateSecondsCalibrated(
+            final int sourceChars,
+            final double prefillTokensPerSecond,
+            final double decodeTokensPerSecond,
+            final double calibratedCharsPerToken) {
+        return estimateSecondsCalibrated(
+                sourceChars,
+                DEFAULT_EXPECTED_OUTPUT_TOKENS,
+                prefillTokensPerSecond,
+                decodeTokensPerSecond,
+                calibratedCharsPerToken);
+    }
+
+    /**
+     * Estimates total generation time (seconds) using measured per-machine calibration when available.
+     *
+     * <p>When both {@code prefillTokensPerSecond} and {@code decodeTokensPerSecond} are {@code > 0}, uses
+     * the linear model {@code promptTokens / prefillTps + outputTokens / decodeTps} (with
+     * {@code calibratedCharsPerToken} for the token estimate when {@code > 0}); otherwise falls back to the
+     * built-in reference-CPU model in {@link #estimateSeconds(int, int)}.</p>
+     *
+     * @param sourceChars              number of source characters that will be sent to the model
+     * @param expectedOutputTokens     number of tokens the model is expected to generate
+     * @param prefillTokensPerSecond   measured prefill throughput, or {@code <= 0} to fall back
+     * @param decodeTokensPerSecond    measured decode throughput, or {@code <= 0} to fall back
+     * @param calibratedCharsPerToken  measured characters per token, or {@code <= 0} to use the default
+     * @return estimated total time in seconds, rounded to the nearest second
+     */
+    public long estimateSecondsCalibrated(
+            final int sourceChars,
+            final int expectedOutputTokens,
+            final double prefillTokensPerSecond,
+            final double decodeTokensPerSecond,
+            final double calibratedCharsPerToken) {
+        if (prefillTokensPerSecond <= 0.0d || decodeTokensPerSecond <= 0.0d) {
+            return estimateSeconds(sourceChars, expectedOutputTokens);
+        }
+        final double charsPerToken =
+                calibratedCharsPerToken > 0.0d ? calibratedCharsPerToken : ESTIMATION_CHARS_PER_TOKEN;
+        final int promptTokens = (int) Math.round(sourceChars / charsPerToken) + PROMPT_TEMPLATE_TOKEN_OVERHEAD;
+        final double seconds = promptTokens / prefillTokensPerSecond + expectedOutputTokens / decodeTokensPerSecond;
+        return Math.round(seconds * ETA_SAFETY_MARGIN);
+    }
+
     /**
      * Formats a second count as a short human-readable string: "{@code ~N s}" below
      * {@link #MINUTE_FORMAT_THRESHOLD_SECONDS}, otherwise "{@code ~N min}".
diff --git a/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunker.java b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunker.java
new file mode 100644
index 0000000..c5884b5
--- /dev/null
+++ b/src/main/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunker.java
@@ -0,0 +1,98 @@
+// @formatter:off
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+// @formatter:on
+package net.ladenthin.maven.llamacpp.aiindex.support;
+
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Splits a source string into chunks for map-reduce summarization of very large files.
+ *
+ * <p>Each chunk is at most {@code maxChars} long and ends at a <strong>line boundary</strong> (the last
+ * {@code \n} within the window) so records/lines are never torn in the middle; if a single line is longer
+ * than {@code maxChars} the chunk is hard-cut. Consecutive chunks may {@code overlap} by a number of
+ * characters so context is not lost at the seam. When the file would produce more than {@code maxChunks}
+ * chunks (and {@code maxChunks > 0}), a representative subset is selected — always including the first and
+ * last chunk and evenly spacing the rest — so the summary samples the <em>whole</em> file, not just its
+ * head. Pure; no I/O.</p>
+ */
+public final class AiSourceChunker {
+
+    /** Utility class; not instantiable. */
+    private AiSourceChunker() {
+        // no-op
+    }
+
+    /**
+     * Chunks {@code source} per the class contract.
+     *
+     * @param source       the full source text
+     * @param maxChars     maximum characters per chunk (must be {@code >= 1})
+     * @param overlapChars characters of overlap between consecutive chunks (clamped to {@code [0, maxChars - 1]})
+     * @param maxChunks    maximum number of chunks to return; {@code <= 0} means unbounded (return all)
+     * @return the chunks in document order (a representative subset when capped); empty if {@code source} is empty
+     * @throws IllegalArgumentException if {@code maxChars < 1}
+     */
+    public static List<String> chunk(
+            final String source, final int maxChars, final int overlapChars, final int maxChunks) {
+        if (maxChars < 1) {
+            throw new IllegalArgumentException("maxChars must be >= 1 but was " + maxChars);
+        }
+        final int length = source.length();
+        final List<String> chunks = new ArrayList<>(length / maxChars + 1);
+        if (length == 0) {
+            return chunks;
+        }
+        final int overlap = Math.max(0, Math.min(overlapChars, maxChars - 1));
+
+        int pos = 0;
+        while (pos < length) {
+            int end = Math.min(pos + maxChars, length);
+            if (end < length) {
+                final int lastNewline = source.lastIndexOf('\n', end - 1);
+                if (lastNewline > pos) {
+                    end = lastNewline + 1;
+                }
+            }
+            chunks.add(source.substring(pos, end));
+            if (end >= length) {
+                break;
+            }
+            pos = Math.max(pos + 1, end - overlap);
+        }
+        return select(chunks, maxChunks);
+    }
+
+    /**
+     * Returns all chunks, or a representative subset of exactly the distinct indices spanning first..last
+     * when there are more than {@code maxChunks} and {@code maxChunks > 0}.
+     *
+     * @param chunks    the natural chunk list
+     * @param maxChunks the cap ({@code <= 0} = unbounded)
+     * @return the (possibly reduced) chunk list
+     */
+    private static List<String> select(final List<String> chunks, final int maxChunks) {
+        final int total = chunks.size();
+        if (maxChunks <= 0 || total <= maxChunks) {
+            return chunks;
+        }
+        final Set<Integer> indices = new LinkedHashSet<>();
+        if (maxChunks == 1) {
+            indices.add(0);
+        } else {
+            for (int i = 0; i < maxChunks; i++) {
+                indices.add((int) Math.round((double) i * (total - 1) / (maxChunks - 1)));
+            }
+        }
+        final List<String> selected = new ArrayList<>(indices.size());
+        for (final int index : indices) {
+            selected.add(chunks.get(index));
+        }
+        return selected;
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibrationTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibrationTest.java
new file mode 100644
index 0000000..2b292c1
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiCalibrationTest.java
@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class AiCalibrationTest {
+
+    @Test
+    public void prefill_defaultsZeroAndRoundTrips() {
+        final AiCalibration c = new AiCalibration();
+        assertThat(c.getPrefillTokensPerSecond(), is(0.0d));
+        c.setPrefillTokensPerSecond(1234.5d);
+        assertThat(c.getPrefillTokensPerSecond(), is(1234.5d));
+    }
+
+    @Test
+    public void decode_defaultsZeroAndRoundTrips() {
+        final AiCalibration c = new AiCalibration();
+        assertThat(c.getDecodeTokensPerSecond(), is(0.0d));
+        c.setDecodeTokensPerSecond(45.6d);
+        assertThat(c.getDecodeTokensPerSecond(), is(45.6d));
+    }
+
+    @Test
+    public void charsPerToken_defaultsZeroAndRoundTrips() {
+        final AiCalibration c = new AiCalibration();
+        assertThat(c.getCharsPerToken(), is(0.0d));
+        c.setCharsPerToken(3.7d);
+        assertThat(c.getCharsPerToken(), is(3.7d));
+    }
+
+    @Test
+    public void toString_includesTheRates() {
+        final AiCalibration c = new AiCalibration();
+        c.setPrefillTokensPerSecond(1000.0d);
+        assertThat(c.toString(), containsString("1000.0"));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounterTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounterTest.java
new file mode 100644
index 0000000..93d4b3d
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactCounterTest.java
@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.nullValue;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class AiFactCounterTest {
+
+    @Test
+    public void label_defaultsNullAndRoundTrips() {
+        final AiFactCounter c = new AiFactCounter();
+        assertThat(c.getLabel(), is(nullValue()));
+        c.setLabel("INSERT rows");
+        assertThat(c.getLabel(), is(equalTo("INSERT rows")));
+    }
+
+    @Test
+    public void pattern_defaultsNullAndRoundTrips() {
+        final AiFactCounter c = new AiFactCounter();
+        assertThat(c.getPattern(), is(nullValue()));
+        c.setPattern("(?m)^INSERT");
+        assertThat(c.getPattern(), is(equalTo("(?m)^INSERT")));
+    }
+
+    @Test
+    public void toString_includesBothFields() {
+        final AiFactCounter c = new AiFactCounter();
+        c.setLabel("tables");
+        c.setPattern("(?m)^CREATE TABLE");
+        final String text = c.toString();
+        assertThat(text, containsString("tables"));
+        assertThat(text, containsString("(?m)^CREATE TABLE"));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupportTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupportTest.java
new file mode 100644
index 0000000..f888d2a
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionSupportTest.java
@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.notNullValue;
+import static org.hamcrest.CoreMatchers.nullValue;
+import static org.hamcrest.CoreMatchers.sameInstance;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+public class AiFactDefinitionSupportTest {
+
+    private static AiFactCounter counter(final String label, final String pattern) {
+        final AiFactCounter c = new AiFactCounter();
+        c.setLabel(label);
+        c.setPattern(pattern);
+        return c;
+    }
+
+    private static AiFactDefinition definition(final String key, final List<AiFactCounter> facts) {
+        final AiFactDefinition d = new AiFactDefinition();
+        d.setKey(key);
+        d.setFacts(facts);
+        return d;
+    }
+
+    private static AiFieldGenerationConfig ruleWithFactsKey(final String factsKey) {
+        final AiFieldGenerationConfig r = new AiFieldGenerationConfig();
+        r.setFactsKey(factsKey);
+        return r;
+    }
+
+    @Test
+    public void facts_returnsTheGroupsCounters() {
+        final List<AiFactCounter> group = Collections.singletonList(counter("rows", "(?m)^INSERT"));
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("sql-facts", group)));
+        assertThat(support.facts("sql-facts"), is(sameInstance(group)));
+    }
+
+    @Test
+    public void facts_unknownKey_throws() {
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("k", Collections.emptyList())));
+        assertThrows(IllegalArgumentException.class, () -> support.facts("nope"));
+    }
+
+    @Test
+    public void facts_groupWithNullFacts_returnsEmptyNotThrow() {
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("empty", null)));
+        assertThat(support.facts("empty").isEmpty(), is(true));
+    }
+
+    @Test
+    public void constructor_nullDefinitions_yieldsEmptyRegistry() {
+        final AiFactDefinitionSupport support = new AiFactDefinitionSupport(null);
+        assertThrows(IllegalArgumentException.class, () -> support.facts("any"));
+    }
+
+    @Test
+    public void constructor_nullKey_throwsNamingIndex() {
+        final AiFactDefinition bad = new AiFactDefinition();
+        final NullPointerException ex = assertThrows(
+                NullPointerException.class, () -> new AiFactDefinitionSupport(Collections.singletonList(bad)));
+        assertThat(ex.getMessage(), is(notNullValue()));
+        assertThat(ex.getMessage(), containsString("factDefinitions[0]"));
+    }
+
+    @Test
+    public void resolveFactsKeys_setsRuleFactsFromRegistry() {
+        final List<AiFactCounter> group = Collections.singletonList(counter("rows", "(?m)^INSERT"));
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("sql-facts", group)));
+        final AiFieldGenerationConfig rule = ruleWithFactsKey("sql-facts");
+
+        support.resolveFactsKeys(Collections.singletonList(rule));
+
+        assertThat(rule.getFacts(), is(sameInstance(group)));
+    }
+
+    @Test
+    public void resolveFactsKeys_ruleWithoutFactsKey_leavesInlineFactsUntouched() {
+        final List<AiFactCounter> inline = Collections.singletonList(counter("x", "y"));
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        rule.setFacts(inline);
+        final AiFactDefinitionSupport support = new AiFactDefinitionSupport(null);
+
+        support.resolveFactsKeys(Collections.singletonList(rule));
+
+        assertThat(rule.getFacts(), is(sameInstance(inline)));
+    }
+
+    @Test
+    public void resolveFactsKeys_factsKeyOverridesInlineFacts() {
+        final List<AiFactCounter> shared = Collections.singletonList(counter("rows", "(?m)^INSERT"));
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("sql-facts", shared)));
+        final AiFieldGenerationConfig rule = ruleWithFactsKey("sql-facts");
+        rule.setFacts(Collections.singletonList(counter("inline", "z")));
+
+        support.resolveFactsKeys(Collections.singletonList(rule));
+
+        assertThat(rule.getFacts(), is(sameInstance(shared)));
+    }
+
+    @Test
+    public void resolveFactsKeys_unknownFactsKey_throws() {
+        final AiFactDefinitionSupport support = new AiFactDefinitionSupport(null);
+        final AiFieldGenerationConfig rule = ruleWithFactsKey("missing");
+        assertThrows(IllegalArgumentException.class, () -> support.resolveFactsKeys(Collections.singletonList(rule)));
+    }
+
+    @Test
+    public void resolveFactsKeys_nullRuleEntry_skipped() {
+        final AiFactDefinitionSupport support = new AiFactDefinitionSupport(null);
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        support.resolveFactsKeys(Arrays.asList(null, rule));
+        assertThat(rule.getFacts(), is(nullValue()));
+    }
+
+    @Test
+    public void resolveFactsKeys_appliesToEveryReferencingRule() {
+        final List<AiFactCounter> group = Collections.singletonList(counter("rows", "(?m)^INSERT"));
+        final AiFactDefinitionSupport support =
+                new AiFactDefinitionSupport(Collections.singletonList(definition("sql-facts", group)));
+        final AiFieldGenerationConfig a = ruleWithFactsKey("sql-facts");
+        final AiFieldGenerationConfig b = ruleWithFactsKey("sql-facts");
+
+        support.resolveFactsKeys(Arrays.asList(a, b));
+
+        assertThat(a.getFacts(), is(notNullValue()));
+        assertThat(b.getFacts(), is(sameInstance(a.getFacts())));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionTest.java
new file mode 100644
index 0000000..0f07be0
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactDefinitionTest.java
@@ -0,0 +1,41 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.equalTo;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.notNullValue;
+import static org.hamcrest.CoreMatchers.nullValue;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+
+public class AiFactDefinitionTest {
+
+    @Test
+    public void key_defaultsNullAndRoundTrips() {
+        final AiFactDefinition d = new AiFactDefinition();
+        assertThat(d.getKey(), is(nullValue()));
+        d.setKey("java-facts");
+        assertThat(d.getKey(), is(equalTo("java-facts")));
+    }
+
+    @Test
+    public void facts_defaultsNullAndRoundTrips() {
+        final AiFactDefinition d = new AiFactDefinition();
+        assertThat(d.getFacts(), is(nullValue()));
+        d.setFacts(Collections.singletonList(new AiFactCounter()));
+        assertThat(d.getFacts(), is(notNullValue()));
+        assertThat(d.getFacts().size(), is(equalTo(1)));
+    }
+
+    @Test
+    public void toString_includesKey() {
+        final AiFactDefinition d = new AiFactDefinition();
+        d.setKey("sql-facts");
+        assertThat(d.toString(), containsString("sql-facts"));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractorTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractorTest.java
new file mode 100644
index 0000000..e2cf199
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFactExtractorTest.java
@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.startsWith;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.Arrays;
+import java.util.Collections;
+import org.junit.jupiter.api.Test;
+
+public class AiFactExtractorTest {
+
+    private static AiFactCounter counter(final String label, final String pattern) {
+        final AiFactCounter c = new AiFactCounter();
+        c.setLabel(label);
+        c.setPattern(pattern);
+        return c;
+    }
+
+    @Test
+    public void factsBlock_nullCounters_returnsEmpty() {
+        assertThat(AiFactExtractor.factsBlock(null, "anything"), is(""));
+    }
+
+    @Test
+    public void factsBlock_emptyCounters_returnsEmpty() {
+        assertThat(AiFactExtractor.factsBlock(Collections.emptyList(), "anything"), is(""));
+    }
+
+    @Test
+    public void factsBlock_countsOccurrencesAcrossTheWholeSource() {
+        // \bboolean\b matches each occurrence (2), regardless of line.
+        final String block = AiFactExtractor.factsBlock(
+                Collections.singletonList(counter("boolean fields", "\\bboolean\\b")), "boolean a; int i; boolean b;");
+        assertThat(block, containsString("boolean fields: 2"));
+    }
+
+    @Test
+    public void factsBlock_multilineAnchorCountsPerLine() {
+        // (?m)^INSERT counts lines starting with INSERT (2), not the CREATE line.
+        final String block = AiFactExtractor.factsBlock(
+                Collections.singletonList(counter("rows", "(?m)^INSERT")), "INSERT a\nINSERT b\nCREATE c\n");
+        assertThat(block, containsString("rows: 2"));
+    }
+
+    @Test
+    public void factsBlock_zeroMatches_reportsZero() {
+        final String block = AiFactExtractor.factsBlock(
+                Collections.singletonList(counter("views", "(?m)^CREATE VIEW")), "no views here");
+        assertThat(block, containsString("views: 0"));
+    }
+
+    @Test
+    public void factsBlock_multipleCounters_joinedWithSeparatorHeaderAndSuffix() {
+        final String block = AiFactExtractor.factsBlock(
+                Arrays.asList(counter("tables", "(?m)^CREATE TABLE"), counter("rows", "(?m)^INSERT")),
+                "CREATE TABLE t\nINSERT a\nINSERT b\n");
+        assertThat(block, startsWith(AiFactExtractor.FACTS_HEADER));
+        assertThat(block, containsString("tables" + AiFactExtractor.LABEL_COUNT_SEPARATOR + "1"));
+        assertThat(block, containsString(AiFactExtractor.ENTRY_SEPARATOR + "rows: 2"));
+        assertThat(block.endsWith(AiFactExtractor.FACTS_SUFFIX), is(true));
+    }
+
+    @Test
+    public void factsBlock_singleCounter_hasNoEntrySeparator() {
+        final String block =
+                AiFactExtractor.factsBlock(Collections.singletonList(counter("rows", "(?m)^INSERT")), "INSERT a\n");
+        assertThat(block.contains(AiFactExtractor.ENTRY_SEPARATOR), is(false));
+    }
+
+    @Test
+    public void factsBlock_counterWithNullLabelOrPattern_isSkipped() {
+        // Both counters malformed -> nothing to report -> empty string.
+        assertThat(AiFactExtractor.factsBlock(Arrays.asList(counter(null, "x"), counter("y", null)), "xxxx"), is(""));
+    }
+
+    @Test
+    public void factsBlock_mixOfValidAndSkipped_reportsOnlyValid() {
+        final String block = AiFactExtractor.factsBlock(
+                Arrays.asList(counter(null, "x"), counter("rows", "(?m)^INSERT")), "INSERT a\n");
+        assertThat(block, startsWith(AiFactExtractor.FACTS_HEADER));
+        assertThat(block, containsString("rows: 1"));
+    }
+
+    @Test
+    public void validate_null_isAllowed() {
+        assertDoesNotThrow(() -> AiFactExtractor.validate(null));
+    }
+
+    @Test
+    public void validate_validCounters_doesNotThrow() {
+        assertDoesNotThrow(() -> AiFactExtractor.validate(Collections.singletonList(counter("rows", "(?m)^INSERT"))));
+    }
+
+    @Test
+    public void validate_nullLabel_throws() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> AiFactExtractor.validate(Collections.singletonList(counter(null, "x"))));
+    }
+
+    @Test
+    public void validate_nullPattern_throws() {
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> AiFactExtractor.validate(Collections.singletonList(counter("x", null))));
+    }
+
+    @Test
+    public void validate_invalidRegex_throwsNamingTheLabel() {
+        final IllegalArgumentException ex = assertThrows(
+                IllegalArgumentException.class,
+                () -> AiFactExtractor.validate(Collections.singletonList(counter("bad", "["))));
+        assertThat(ex.getMessage(), containsString("bad"));
+    }
+
+    @Test
+    public void validate_nullEntryInList_isSkipped() {
+        assertDoesNotThrow(() -> AiFactExtractor.validate(Collections.singletonList(null)));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfigTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfigTest.java
index 9282747..9ad8a68 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfigTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationConfigTest.java
@@ -68,4 +68,46 @@ public void skip_defaultsFalseAndTogglesTrue() {
         c.setSkip(true);
         assertThat(c.isSkip(), is(true));
     }
+
+    @Test
+    public void onOversize_defaultsNullAndRoundTrips() {
+        final AiFieldGenerationConfig c = new AiFieldGenerationConfig();
+        assertThat(c.getOnOversize(), is(nullValue()));
+        c.setOnOversize("mapReduce");
+        assertThat(c.getOnOversize(), is(equalTo("mapReduce")));
+    }
+
+    @Test
+    public void oversizeStrategy_defaultsFailAndReflectsToken() {
+        final AiFieldGenerationConfig c = new AiFieldGenerationConfig();
+        assertThat(c.getOversizeStrategy(), is(AiOversizeStrategy.FAIL));
+        c.setOnOversize("deterministic");
+        assertThat(c.getOversizeStrategy(), is(AiOversizeStrategy.DETERMINISTIC));
+    }
+
+    @Test
+    public void maxChunks_defaultsZeroAndRoundTrips() {
+        final AiFieldGenerationConfig c = new AiFieldGenerationConfig();
+        assertThat(c.getMaxChunks(), is(equalTo(0)));
+        c.setMaxChunks(7);
+        assertThat(c.getMaxChunks(), is(equalTo(7)));
+    }
+
+    @Test
+    public void facts_defaultsNullAndRoundTrips() {
+        final AiFieldGenerationConfig c = new AiFieldGenerationConfig();
+        assertThat(c.getFacts(), is(nullValue()));
+        final AiFactCounter counter = new AiFactCounter();
+        c.setFacts(java.util.Collections.singletonList(counter));
+        assertThat(c.getFacts(), is(notNullValue()));
+        assertThat(c.getFacts().size(), is(equalTo(1)));
+    }
+
+    @Test
+    public void factsKey_defaultsNullAndRoundTrips() {
+        final AiFieldGenerationConfig c = new AiFieldGenerationConfig();
+        assertThat(c.getFactsKey(), is(nullValue()));
+        c.setFactsKey("java-facts");
+        assertThat(c.getFactsKey(), is(equalTo("java-facts")));
+    }
 }
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelectorTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelectorTest.java
index fa3d415..10f08c5 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelectorTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiFieldGenerationSelectorTest.java
@@ -161,6 +161,20 @@ public void validate_fallbackThatIsAlsoSkip_throws() {
         assertThrows(IllegalArgumentException.class, () -> selector.validate(Collections.singletonList(fb)));
     }
 
+    @Test
+    public void validate_invalidOnOversize_throws() {
+        final AiFieldGenerationConfig r = route("java", extCond(".java"), 0);
+        r.setOnOversize("nonsense");
+        assertThrows(IllegalArgumentException.class, () -> selector.validate(Collections.singletonList(r)));
+    }
+
+    @Test
+    public void validate_validOnOversize_passes() {
+        final AiFieldGenerationConfig r = route("java", extCond(".java"), 0);
+        r.setOnOversize("mapReduce");
+        assertDoesNotThrow(() -> selector.validate(Collections.singletonList(r)));
+    }
+
     @Test
     public void validate_routeMissingPromptKey_throws() {
         final AiFieldGenerationConfig bad = new AiFieldGenerationConfig();
@@ -195,5 +209,25 @@ public void validate_invalidConditionInRule_throws() {
         final AiFieldGenerationConfig bad = route("p", new AiCondition(), 0);
         assertThrows(IllegalArgumentException.class, () -> selector.validate(Collections.singletonList(bad)));
     }
+
+    @Test
+    public void validate_invalidFactPattern_throws() {
+        final AiFieldGenerationConfig r = route("java", extCond(".java"), 0);
+        final AiFactCounter bad = new AiFactCounter();
+        bad.setLabel("broken");
+        bad.setPattern("[");
+        r.setFacts(Collections.singletonList(bad));
+        assertThrows(IllegalArgumentException.class, () -> selector.validate(Collections.singletonList(r)));
+    }
+
+    @Test
+    public void validate_validFactPattern_passes() {
+        final AiFieldGenerationConfig r = route("java", extCond(".java"), 0);
+        final AiFactCounter ok = new AiFactCounter();
+        ok.setLabel("rows");
+        ok.setPattern("(?m)^INSERT");
+        r.setFacts(Collections.singletonList(ok));
+        assertDoesNotThrow(() -> selector.validate(Collections.singletonList(r)));
+    }
     // </editor-fold>
 }
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupportTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupportTest.java
index 329c34e..656a5aa 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupportTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionSupportTest.java
@@ -7,6 +7,7 @@
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.CoreMatchers.is;
 import static org.hamcrest.CoreMatchers.notNullValue;
+import static org.hamcrest.CoreMatchers.sameInstance;
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
@@ -67,6 +68,11 @@ public void getConfig_knownKey_propagatesAllFields() {
         definition.setTopNSigma(1.3f);
         definition.setRepeatPenalty(1.15f);
         definition.setStopStrings(Arrays.asList("</s>", "STOP"));
+        final AiCalibration calibration = new AiCalibration();
+        calibration.setPrefillTokensPerSecond(900.0d);
+        calibration.setDecodeTokensPerSecond(45.0d);
+        calibration.setCharsPerToken(4.2d);
+        definition.setCalibration(calibration);
         final AiModelDefinitionSupport support = new AiModelDefinitionSupport(Arrays.asList(definition));
 
         // act
@@ -89,6 +95,9 @@ public void getConfig_knownKey_propagatesAllFields() {
         assertThat(config.getTopNSigma(), is(equalTo(1.3f)));
         assertThat(config.getRepeatPenalty(), is(equalTo(1.15f)));
         assertThat(config.getStopStrings(), is(equalTo(Arrays.asList("</s>", "STOP"))));
+        // The calibration is propagated — kills the void-call mutant that would drop the
+        // setCalibration(...) copy from toConfig().
+        assertThat(config.getCalibration(), is(sameInstance(calibration)));
         // Non-default cachePrompt propagates — kills the void-call mutant that would drop the
         // setCachePrompt(...) copy from toConfig().
         assertThat(config.isCachePrompt(), is(false));
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionTest.java
index 7d327d0..d618635 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiModelDefinitionTest.java
@@ -6,6 +6,7 @@
 import static org.hamcrest.CoreMatchers.hasItem;
 import static org.hamcrest.CoreMatchers.is;
 import static org.hamcrest.CoreMatchers.nullValue;
+import static org.hamcrest.CoreMatchers.sameInstance;
 import static org.hamcrest.MatcherAssert.assertThat;
 
 import java.util.Arrays;
@@ -30,6 +31,18 @@ public void stopStringsNullByDefault() {
         assertThat(new AiModelDefinition().getStopStrings(), is(nullValue()));
     }
 
+    @Test
+    public void calibrationNullByDefaultAndRoundTrips() {
+        final AiModelDefinition d = new AiModelDefinition();
+        assertThat(d.getCalibration(), is(nullValue()));
+        final AiCalibration calibration = new AiCalibration();
+        calibration.setPrefillTokensPerSecond(1000.0d);
+        d.setCalibration(calibration);
+        // Asserting the same instance kills the empty-return mutant on the getter and the
+        // assignment-removal mutant on the setter.
+        assertThat(d.getCalibration(), is(sameInstance(calibration)));
+    }
+
     @Test
     public void stopStringsRoundTrip() {
         AiModelDefinition d = new AiModelDefinition();
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategyTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategyTest.java
new file mode 100644
index 0000000..d38f946
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/AiOversizeStrategyTest.java
@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+public class AiOversizeStrategyTest {
+
+    @Test
+    public void defaultIsFail() {
+        assertThat(AiOversizeStrategy.DEFAULT, is(AiOversizeStrategy.FAIL));
+    }
+
+    @Test
+    public void configValuesAreTheExpectedTokens() {
+        assertThat(AiOversizeStrategy.FAIL.configValue(), is("fail"));
+        assertThat(AiOversizeStrategy.SAMPLE.configValue(), is("sample"));
+        assertThat(AiOversizeStrategy.MAP_REDUCE.configValue(), is("mapReduce"));
+        assertThat(AiOversizeStrategy.DETERMINISTIC.configValue(), is("deterministic"));
+    }
+
+    @Test
+    public void fromConfig_nullOrBlank_isDefault() {
+        assertThat(AiOversizeStrategy.fromConfig(null), is(AiOversizeStrategy.FAIL));
+        assertThat(AiOversizeStrategy.fromConfig(""), is(AiOversizeStrategy.FAIL));
+        assertThat(AiOversizeStrategy.fromConfig("   "), is(AiOversizeStrategy.FAIL));
+    }
+
+    @Test
+    public void fromConfig_eachToken_parses() {
+        assertThat(AiOversizeStrategy.fromConfig("fail"), is(AiOversizeStrategy.FAIL));
+        assertThat(AiOversizeStrategy.fromConfig("sample"), is(AiOversizeStrategy.SAMPLE));
+        assertThat(AiOversizeStrategy.fromConfig("mapReduce"), is(AiOversizeStrategy.MAP_REDUCE));
+        assertThat(AiOversizeStrategy.fromConfig("deterministic"), is(AiOversizeStrategy.DETERMINISTIC));
+    }
+
+    @Test
+    public void fromConfig_isCaseInsensitiveAndTrimmed() {
+        assertThat(AiOversizeStrategy.fromConfig("  MAPREDUCE  "), is(AiOversizeStrategy.MAP_REDUCE));
+        assertThat(AiOversizeStrategy.fromConfig("Sample"), is(AiOversizeStrategy.SAMPLE));
+    }
+
+    @Test
+    public void fromConfig_unknown_throwsWithValue() {
+        final IllegalArgumentException ex =
+                assertThrows(IllegalArgumentException.class, () -> AiOversizeStrategy.fromConfig("nonsense"));
+        assertThat(ex.getMessage(), containsString("nonsense"));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/JavaStructureFactPatternsTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/JavaStructureFactPatternsTest.java
new file mode 100644
index 0000000..8bec48d
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/config/JavaStructureFactPatternsTest.java
@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.config;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Validates the Java structural {@code <facts>} regexes shipped in the POM's {@code java-facts} group,
+ * in the real {@link java.util.regex} engine (the same engine {@code AiFactExtractor} uses), against the
+ * tricky-case self-tests. These are deliberately approximate ("methods (approx)", "field declarations")
+ * — the tests pin the accepted false-positive/negative boundary so the patterns cannot silently drift.
+ *
+ * <p>Keep these three patterns in sync with the {@code java-facts} {@code <factDefinitions>} in
+ * {@code pom.xml} (there they are XML-escaped: {@code <} becomes {@code &lt;}).</p>
+ */
+public class JavaStructureFactPatternsTest {
+
+    /** Methods: modifiers, type params, generic/array return, multi-line params, throws, {@code {} or ;}. */
+    private static final String METHOD_PATTERN =
+            "(?m)^[ \\t]*(?:(?:public|private|protected|static|final|abstract|default|synchronized|native|strictfp)"
+                    + "[ \\t]+)*"
+                    + "(?:<[^>]+>[ \\t]*)?"
+                    + "(?!(?:if|for|while|switch|catch|return|new|else|do|try|synchronized|assert|throw)\\b)"
+                    + "[A-Za-z_$][\\w$.]*(?:<[^;{}=]*>)?(?:\\[\\])*[ \\t]+"
+                    + "([A-Za-z_$]\\w*)[ \\t]*"
+                    + "\\([^;{]*\\)"
+                    + "(?:[ \\t]*throws[ \\t][\\w$., \\t]+)?"
+                    + "[ \\t]*[{;]";
+
+    /** Field declarations that carry a STRONG modifier (final-only excluded, to skip final locals). */
+    private static final String FIELD_PATTERN = "(?m)^[ \\t]*"
+            + "(?:(?:public|private|protected|static|transient|volatile|final)[ \\t]+)*"
+            + "(?:public|private|protected|static|transient|volatile)[ \\t]+"
+            + "(?:(?:public|private|protected|static|transient|volatile|final)[ \\t]+)*"
+            + "(?!class\\b|interface\\b|enum\\b|record\\b|void\\b|new\\b)"
+            + "[A-Za-z_$][\\w$.]*(?:<[^;{}=]*>)?(?:\\[\\])*[ \\t]+"
+            + "([A-Za-z_$]\\w*(?:[ \\t]*,[ \\t]*[A-Za-z_$]\\w*)*)"
+            + "[ \\t]*(?:=[^;]*)?;";
+
+    /** Constructors: capitalized name directly followed by {@code (}, ending in {@code {}. */
+    private static final String CTOR_PATTERN = "(?m)^[ \\t]*(?:(?:public|private|protected)[ \\t]+)?"
+            + "([A-Z][A-Za-z0-9_$]*)[ \\t]*\\([^;{]*\\)"
+            + "(?:[ \\t]*throws[ \\t][\\w$., \\t]+)?[ \\t]*\\{";
+
+    private static int count(final String pattern, final String source) {
+        final Matcher matcher = Pattern.compile(pattern).matcher(source);
+        int count = 0;
+        while (matcher.find()) {
+            count++;
+        }
+        return count;
+    }
+
+    // <editor-fold defaultstate="collapsed" desc="methods">
+    @Test
+    public void method_annotatedOnOwnLine_counts() {
+        assertThat(count(METHOD_PATTERN, "@Override\npublic int foo() {\n}"), is(1));
+    }
+
+    @Test
+    public void method_genericMultilineThrows_counts() {
+        assertThat(count(METHOD_PATTERN, "public <T> T bar(List<T> x,\n int y) throws IOException {\n}"), is(1));
+    }
+
+    @Test
+    public void method_arrayReturn_counts() {
+        assertThat(count(METHOD_PATTERN, "int[] baz() {\n}"), is(1));
+    }
+
+    @Test
+    public void method_abstractSemicolon_counts() {
+        assertThat(count(METHOD_PATTERN, "abstract void run();"), is(1));
+    }
+
+    @Test
+    public void method_doesNotCountControlStructures() {
+        assertThat(count(METHOD_PATTERN, "if (foo()) { bar(); }"), is(0));
+        assertThat(count(METHOD_PATTERN, "        for (int i = 0; i < n; i++) {\n}"), is(0));
+    }
+
+    @Test
+    public void method_doesNotCountCalls() {
+        assertThat(count(METHOD_PATTERN, "        obj.doThing(x);\n        foo(y);"), is(0));
+        assertThat(count(METHOD_PATTERN, "        return compute(x);"), is(0));
+    }
+
+    @Test
+    public void method_doesNotCountLambda() {
+        assertThat(count(METHOD_PATTERN, "        Runnable r = () -> doWork();"), is(0));
+    }
+    // </editor-fold>
+
+    // <editor-fold defaultstate="collapsed" desc="fields">
+    @Test
+    public void field_multipleDeclarators_countAsOneStatement() {
+        // AiFactExtractor counts matches (statements), so "int a, b, c;" is ONE field declaration.
+        assertThat(count(FIELD_PATTERN, "    private int a, b, c;"), is(1));
+    }
+
+    @Test
+    public void field_staticFinalWithInit_counts() {
+        assertThat(count(FIELD_PATTERN, "    public static final String NAME = \"x\";"), is(1));
+    }
+
+    @Test
+    public void field_genericType_counts() {
+        assertThat(count(FIELD_PATTERN, "    private Map<String, List<X>> m;"), is(1));
+    }
+
+    @Test
+    public void field_transientArray_counts() {
+        assertThat(count(FIELD_PATTERN, "    transient Object[] elementData;"), is(1));
+    }
+
+    @Test
+    public void field_doesNotCountLocalsOrFinalLocals() {
+        assertThat(count(FIELD_PATTERN, "        int local = 5;"), is(0));
+        assertThat(count(FIELD_PATTERN, "        final int s;"), is(0));
+        assertThat(count(FIELD_PATTERN, "        final Object[] es = elementData;"), is(0));
+    }
+    // </editor-fold>
+
+    // <editor-fold defaultstate="collapsed" desc="constructors">
+    @Test
+    public void ctor_counts() {
+        assertThat(count(CTOR_PATTERN, "    public Foo(int x) {\n}"), is(1));
+    }
+
+    @Test
+    public void ctor_doesNotCountLowercaseMethod() {
+        assertThat(count(CTOR_PATTERN, "    public void foo(int x) {\n}"), is(0));
+    }
+    // </editor-fold>
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurementTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurementTest.java
new file mode 100644
index 0000000..b3c5a00
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationMeasurementTest.java
@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.indexer;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class AiCalibrationMeasurementTest {
+
+    @Test
+    public void accessorsReturnConstructorValues() {
+        final AiCalibrationMeasurement m = new AiCalibrationMeasurement(3.5d, 900.0d, 45.0d, 4.2d, 1200.0d);
+        assertThat(m.loadSeconds(), is(3.5d));
+        assertThat(m.prefillTokensPerSecond(), is(900.0d));
+        assertThat(m.decodeTokensPerSecond(), is(45.0d));
+        assertThat(m.charsPerToken(), is(4.2d));
+        assertThat(m.midPrefillTokensPerSecond(), is(1200.0d));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunnerTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunnerTest.java
new file mode 100644
index 0000000..01c0dab
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiCalibrationRunnerTest.java
@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.indexer;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import net.ladenthin.maven.llamacpp.aiindex.CommonTestFixtures;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationProvider;
+import net.ladenthin.maven.llamacpp.aiindex.provider.AiGenerationTimings;
+import net.ladenthin.maven.llamacpp.aiindex.provider.MockAiGenerationProvider;
+import org.junit.jupiter.api.Test;
+
+public class AiCalibrationRunnerTest {
+
+    private static AiPromptPreparationSupport prep() {
+        return new AiPromptPreparationSupport(new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions()));
+    }
+
+    private static AiGenerationConfig config() {
+        final AiGenerationConfig config = new AiGenerationConfig();
+        config.setContextSize(2048);
+        config.setCharsPerToken(4);
+        config.setMaxOutputTokens(64);
+        return config;
+    }
+
+    @Test
+    public void measure_withMockProvider_reportsTheProvidersSyntheticThroughput() throws Exception {
+        final AiCalibrationRunner runner = new AiCalibrationRunner();
+        final AiCalibrationMeasurement m = runner.measure(
+                new MockAiGenerationProvider(), config(), CommonTestFixtures.PROMPT_KEY_FILE_BODY, prep());
+
+        // The mock reports 1000 prefill / 100 decode tok/s and ~4 chars/token (the synthetic source rounds
+        // up to whole lines, so it is a hair under 4); the runner surfaces them.
+        assertThat(m.prefillTokensPerSecond(), is(1000.0d));
+        assertThat(m.decodeTokensPerSecond(), is(100.0d));
+        assertThat(m.charsPerToken() > 3.9d && m.charsPerToken() <= 4.0d, is(true));
+        assertThat(m.loadSeconds() >= 0.0d, is(true));
+    }
+
+    @Test
+    public void measure_zeroRateProvider_takesWallClockFallback() throws Exception {
+        // A provider that reports zero rates (like the real JNI path) forces the wall-clock fallback; the
+        // measured charsPerToken then comes from the config (4), proving the fallback branch ran.
+        final AiGenerationProvider zeroRateProvider = new AiGenerationProvider() {
+            @Override
+            public String generate(final AiGenerationRequest request) {
+                return "t";
+            }
+
+            @Override
+            public AiGenerationTimings generateWithTimings(final AiGenerationRequest request) {
+                return new AiGenerationTimings("t", 0, 0.0d, 0, 0.0d);
+            }
+        };
+        final AiCalibrationMeasurement m = new AiCalibrationRunner()
+                .measure(zeroRateProvider, config(), CommonTestFixtures.PROMPT_KEY_FILE_BODY, prep());
+        assertThat(m.charsPerToken(), is(4.0d));
+        assertThat(m.prefillTokensPerSecond() >= 0.0d, is(true));
+        assertThat(m.decodeTokensPerSecond() >= 0.0d, is(true));
+    }
+
+    @Test
+    public void windowChars_isPositiveForANormalWindow() {
+        final long window =
+                new AiCalibrationRunner().windowChars(config(), CommonTestFixtures.PROMPT_KEY_FILE_BODY, prep());
+        assertThat(window > 0, is(true));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportRealModelTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportRealModelTest.java
new file mode 100644
index 0000000..16faeba
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportRealModelTest.java
@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.indexer;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.startsWith;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.Collections;
+import net.ladenthin.maven.llamacpp.aiindex.CommonTestFixtures;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinition;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationResult;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptPreparationSupport;
+import net.ladenthin.maven.llamacpp.aiindex.prompt.AiPromptSupport;
+import net.ladenthin.maven.llamacpp.aiindex.provider.LlamaCppJniAiGenerationProvider;
+import net.ladenthin.maven.llamacpp.aiindex.provider.LlamaCppJniConfig;
+import org.apache.maven.plugin.logging.SystemStreamLog;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.Test;
+
+/**
+ * End-to-end smoke test of the {@code onOversize=mapReduce} pipeline (chunk &rarr; hierarchical reduce)
+ * plus the exact {@code <facts>} block, driven by the <em>real</em> llama.cpp JNI provider and the small
+ * bundled test model. Skipped unless the native lib is available and {@code -DrunNativeLlamaTests=true}.
+ * Unit tests cover the orchestration with the mock provider; this proves the same path works against a
+ * real model (real generation, real prompt-cache reuse, real trimming).
+ */
+public class AiFieldGenerationSupportRealModelTest {
+
+    private static final String MODEL_PATH = Paths.get("src", "test", "resources", "SmolLM2-135M-Instruct-Q3_K_M.gguf")
+            .toAbsolutePath()
+            .toString();
+
+    /** Small context so a modest synthetic source is over-window and triggers map-reduce with the tiny model. */
+    private static final int SMALL_CONTEXT = 512;
+
+    private static final String MODEL_KEY = "smol";
+
+    private static AiMdHeader header() {
+        return new AiMdHeader(
+                "Data.java", "1.0", "0", "2026-01-01T00:00:00Z", "2026-01-01T00:00:00Z", "0", "0", "file");
+    }
+
+    private static String largeSource(final int lines) {
+        final StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < lines; i++) {
+            sb.append("line ").append(i).append(" = value;\n");
+        }
+        return sb.toString();
+    }
+
+    @Test
+    public void mapReduceWithFacts_realModel_producesFactsPlusSummary() throws Exception {
+        Assumptions.assumeTrue(
+                Boolean.getBoolean("runNativeLlamaTests"),
+                "Native llama test disabled. Enable with -DrunNativeLlamaTests=true");
+        Assumptions.assumeTrue(Files.exists(Paths.get(MODEL_PATH)), "Model file missing: " + MODEL_PATH);
+
+        final AiModelDefinition def = new AiModelDefinition();
+        def.setKey(MODEL_KEY);
+        def.setModelPath(MODEL_PATH);
+        def.setContextSize(SMALL_CONTEXT);
+        def.setMaxOutputTokens(48);
+        def.setCharsPerToken(3);
+        final AiModelDefinitionSupport models = new AiModelDefinitionSupport(Collections.singletonList(def));
+
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
+        final AiPromptPreparationSupport prep = new AiPromptPreparationSupport(promptSupport);
+        final LlamaCppJniConfig jniConfig = new LlamaCppJniConfig(
+                null,
+                MODEL_PATH,
+                SMALL_CONTEXT,
+                48,
+                0.15f,
+                8,
+                AiGenerationConfig.DEFAULT_TOP_P,
+                AiGenerationConfig.DEFAULT_TOP_K,
+                AiGenerationConfig.DEFAULT_MIN_P,
+                AiGenerationConfig.DEFAULT_TOP_N_SIGMA,
+                AiGenerationConfig.DEFAULT_REPEAT_PENALTY,
+                AiGenerationConfig.DEFAULT_CHAT_TEMPLATE_ENABLE_THINKING,
+                AiGenerationConfig.DEFAULT_CACHE_PROMPT,
+                AiGenerationConfig.DEFAULT_SWA_FULL,
+                AiGenerationConfig.DEFAULT_CACHE_REUSE,
+                AiGenerationConfig.DEFAULT_GPU_LAYERS,
+                AiGenerationConfig.DEFAULT_MAIN_GPU,
+                AiGenerationConfig.DEFAULT_DEVICES,
+                AiGenerationConfig.DEFAULT_REASONING_EFFORT,
+                AiGenerationConfig.DEFAULT_REASONING_BUDGET_TOKENS,
+                AiGenerationConfig.DEFAULT_DRY_MULTIPLIER,
+                AiGenerationConfig.DEFAULT_DRY_BASE,
+                AiGenerationConfig.DEFAULT_DRY_ALLOWED_LENGTH,
+                AiGenerationConfig.DEFAULT_DRY_PENALTY_LAST_N,
+                Collections.emptyList(),
+                Collections.emptyList());
+
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        rule.setPromptKey(CommonTestFixtures.PROMPT_KEY_FILE_BODY);
+        rule.setAiDefinitionKey(MODEL_KEY);
+        rule.setOnOversize("mapReduce");
+        rule.setMaxChunks(2);
+        final AiFactCounter counter = new AiFactCounter();
+        counter.setLabel("lines");
+        counter.setPattern("(?m)^line ");
+        rule.setFacts(Collections.singletonList(counter));
+
+        final int lineCount = 400;
+        final String source = largeSource(lineCount);
+        final Path contextFile = Files.createTempFile("Data", ".java");
+
+        try (LlamaCppJniAiGenerationProvider provider = new LlamaCppJniAiGenerationProvider(jniConfig, promptSupport)) {
+            final AiFieldGenerationSupport support =
+                    new AiFieldGenerationSupport(new SystemStreamLog(), provider, prep, models);
+            final AiGenerationResult result = support.processFieldGenerations(
+                    Collections.singletonList(rule), contextFile, "file", source, header());
+
+            // The exact facts (counted over the whole source) lead the body; the map-reduced AI summary
+            // follows. This proves the real-model chunk -> hierarchical-reduce path completes end-to-end.
+            assertThat(result.body(), startsWith(AiFactExtractor.FACTS_HEADER));
+            assertThat(result.body(), containsString("lines: " + lineCount));
+            assertThat(
+                    result.body().length()
+                            > AiFactExtractor.factsBlock(rule.getFacts(), source)
+                                    .length(),
+                    is(true));
+        }
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportTest.java
index 47ac267..a989c07 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/indexer/AiFieldGenerationSupportTest.java
@@ -6,14 +6,23 @@
 import static org.hamcrest.CoreMatchers.containsString;
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.CoreMatchers.startsWith;
 import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicInteger;
 import net.ladenthin.maven.llamacpp.aiindex.CommonTestFixtures;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactCounter;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFactExtractor;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiFieldGenerationConfig;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinition;
+import net.ladenthin.maven.llamacpp.aiindex.config.AiModelDefinitionSupport;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationResult;
 import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
@@ -57,6 +66,12 @@ public List<String> getCapturedInfos() {
         }
     }
 
+    /**
+     * Lower bound on chunks needed to force a second reduce round: strictly above the production
+     * {@code MAX_REDUCE_FANIN} (16) so the reduce cannot combine every partial in a single call.
+     */
+    private static final long MIN_CHUNKS_FOR_TWO_REDUCE_ROUNDS = 16L;
+
     private WarnCapturingLog capturingLog;
 
     @BeforeEach
@@ -288,4 +303,278 @@ public String generate(final AiGenerationRequest request) {
         }
     }
     // </editor-fold>
+
+    // <editor-fold defaultstate="collapsed" desc="onOversize strategies">
+
+    /** A model whose tiny static input window forces every non-trivial source to be over-window. */
+    private static AiModelDefinitionSupport tinyWindowModel(final String key) {
+        final AiModelDefinition def = new AiModelDefinition();
+        def.setKey(key);
+        def.setModelPath("unused.gguf");
+        // contextSize 1 x charsPerToken 1 minus overhead -> computed maxInputChars clamps to 0, so any
+        // non-empty source is over-window and triggers the onOversize strategy.
+        def.setContextSize(1);
+        def.setCharsPerToken(1);
+        return new AiModelDefinitionSupport(Arrays.asList(def));
+    }
+
+    private AiFieldGenerationSupport supportWith(final AiGenerationProvider provider, final String modelKey) {
+        return supportWithModels(provider, tinyWindowModel(modelKey));
+    }
+
+    private AiFieldGenerationSupport supportWithModels(
+            final AiGenerationProvider provider, final AiModelDefinitionSupport models) {
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
+        return new AiFieldGenerationSupport(
+                capturingLog, provider, new AiPromptPreparationSupport(promptSupport), models);
+    }
+
+    /** A model with a normal window, so a small source fits and is NOT treated as over-window. */
+    private static AiModelDefinitionSupport normalWindowModel(final String key) {
+        final AiModelDefinition def = new AiModelDefinition();
+        def.setKey(key);
+        def.setModelPath("unused.gguf");
+        def.setContextSize(2048);
+        def.setCharsPerToken(4);
+        def.setMaxOutputTokens(64);
+        return new AiModelDefinitionSupport(Arrays.asList(def));
+    }
+
+    private static AiFieldGenerationConfig oversizeRule(
+            final String modelKey, final String onOversize, final int maxChunks) {
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        rule.setPromptKey(CommonTestFixtures.PROMPT_KEY_FILE_BODY);
+        rule.setAiDefinitionKey(modelKey);
+        rule.setOnOversize(onOversize);
+        rule.setMaxChunks(maxChunks);
+        return rule;
+    }
+
+    private static String largeSource(final int lines) {
+        final StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < lines; i++) {
+            sb.append("line ").append(i).append('\n');
+        }
+        return sb.toString();
+    }
+
+    @Test
+    public void onOversize_deterministic_skipsModelAndEmitsMetadataBody() throws Exception {
+        final Path contextFile = Files.createTempFile("Huge", ".java");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            return "MODEL OUTPUT";
+        };
+        final AiFieldGenerationSupport support = supportWith(provider, "m");
+
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(oversizeRule("m", "deterministic", 0)),
+                contextFile,
+                "file",
+                largeSource(500),
+                anyHeader());
+
+        assertThat(calls.get(), is(equalTo(0)));
+        assertThat(result.body(), containsString("deterministically (no AI)"));
+    }
+
+    @Test
+    public void onOversize_mapReduce_callsModelPerChunkPlusReduce() throws Exception {
+        final Path contextFile = Files.createTempFile("Huge", ".java");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            return "PARTIAL";
+        };
+        final AiFieldGenerationSupport support = supportWith(provider, "m");
+
+        // ~3600 chars > 1000-char chunk budget -> several chunks; maxChunks=2 caps to 2 mapped + 1 reduce.
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(oversizeRule("m", "mapReduce", 2)),
+                contextFile,
+                "file",
+                largeSource(600),
+                anyHeader());
+
+        assertThat(calls.get(), is(equalTo(3)));
+        assertThat(result.body(), is(equalTo("PARTIAL")));
+    }
+
+    @Test
+    public void onOversize_mapReduce_withFacts_prependsExactWholeFileCountsToBody() throws Exception {
+        final Path contextFile = Files.createTempFile("Huge", ".java");
+        final AiGenerationProvider provider = request -> "PARTIAL";
+        final AiFieldGenerationSupport support = supportWith(provider, "m");
+
+        final AiFieldGenerationConfig rule = oversizeRule("m", "mapReduce", 2);
+        final AiFactCounter counter = new AiFactCounter();
+        counter.setLabel("lines");
+        counter.setPattern("(?m)^line ");
+        rule.setFacts(Collections.singletonList(counter));
+
+        // largeSource(600) has exactly 600 lines beginning with "line "; the AI (mock) never sees them all,
+        // but the deterministic facts block counts every one over the FULL source and is prepended.
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(rule), contextFile, "file", largeSource(600), anyHeader());
+
+        assertThat(result.body(), startsWith(AiFactExtractor.FACTS_HEADER));
+        assertThat(result.body(), containsString("lines: 600"));
+        assertThat(result.body(), containsString("PARTIAL"));
+    }
+
+    @Test
+    public void facts_prependedOnNonOversizeFile() throws Exception {
+        // A small source that fits the window (NOT oversize) still gets the exact facts block prepended,
+        // so downstream agents get authoritative counts in every summary, not just huge-file ones.
+        final Path contextFile = Files.createTempFile("Small", ".java");
+        final AiGenerationProvider provider = request -> "AI SUMMARY";
+        final AiFieldGenerationSupport support = supportWithModels(provider, normalWindowModel("m"));
+
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        rule.setPromptKey(CommonTestFixtures.PROMPT_KEY_FILE_BODY);
+        rule.setAiDefinitionKey("m");
+        final AiFactCounter counter = new AiFactCounter();
+        counter.setLabel("boolean fields");
+        counter.setPattern("\\bboolean\\b");
+        rule.setFacts(Collections.singletonList(counter));
+
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(rule), contextFile, "file", "boolean a; boolean b; int c;", anyHeader());
+
+        assertThat(result.body(), startsWith(AiFactExtractor.FACTS_HEADER));
+        assertThat(result.body(), containsString("boolean fields: 2"));
+        assertThat(result.body(), containsString("AI SUMMARY"));
+    }
+
+    private static AiFieldGenerationConfig plainRoute(final String modelKey) {
+        final AiFieldGenerationConfig rule = new AiFieldGenerationConfig();
+        rule.setPromptKey(CommonTestFixtures.PROMPT_KEY_FILE_BODY);
+        rule.setAiDefinitionKey(modelKey);
+        return rule;
+    }
+
+    @Test
+    public void generate_contextOverflowThenSuccess_retriesWithSmallerWindowAndSucceeds() throws Exception {
+        final Path contextFile = Files.createTempFile("Dense", ".sql");
+        final AtomicInteger calls = new AtomicInteger();
+        // Fits the char window but the provider rejects the first prompt as over-context (token-dense);
+        // the retry with a smaller window then succeeds.
+        final AiGenerationProvider provider = request -> {
+            if (calls.getAndIncrement() == 0) {
+                throw new RuntimeException("request (16549 tokens) exceeds the available context size (16384 tokens)");
+            }
+            return "OK";
+        };
+        final AiFieldGenerationSupport support = supportWithModels(provider, normalWindowModel("m"));
+
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(plainRoute("m")), contextFile, "file", "small source", anyHeader());
+
+        assertThat(result.body(), is(equalTo("OK")));
+        assertThat(calls.get(), is(equalTo(2)));
+    }
+
+    @Test
+    public void generate_persistentContextOverflow_rethrowsAfterRetrying() throws Exception {
+        final Path contextFile = Files.createTempFile("Dense", ".sql");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            throw new RuntimeException("request exceeds the available context size (16384 tokens)");
+        };
+        final AiFieldGenerationSupport support = supportWithModels(provider, normalWindowModel("m"));
+
+        assertThrows(
+                RuntimeException.class,
+                () -> support.processFieldGenerations(
+                        Collections.singletonList(plainRoute("m")), contextFile, "file", "small source", anyHeader()));
+        // Retried before giving up (more than the single initial attempt).
+        assertThat(calls.get() > 1, is(true));
+    }
+
+    @Test
+    public void generate_nonOverflowRuntimeException_propagatesWithoutRetry() throws Exception {
+        final Path contextFile = Files.createTempFile("X", ".sql");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            throw new RuntimeException("some unrelated failure");
+        };
+        final AiFieldGenerationSupport support = supportWithModels(provider, normalWindowModel("m"));
+
+        assertThrows(
+                RuntimeException.class,
+                () -> support.processFieldGenerations(
+                        Collections.singletonList(plainRoute("m")), contextFile, "file", "small source", anyHeader()));
+        assertThat(calls.get(), is(equalTo(1)));
+    }
+
+    @Test
+    public void onOversize_mapReduce_unbounded_reducesHierarchicallyInMultipleRounds() throws Exception {
+        final Path contextFile = Files.createTempFile("Huge", ".java");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            return "PARTIAL";
+        };
+        final AiFieldGenerationSupport support = supportWith(provider, "m");
+
+        // maxChunks=0 (unbounded) over a large source -> far more than MAX_REDUCE_FANIN chunks, so the
+        // reduce cannot combine every partial in one call and must recurse: a second reduce round appears.
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(oversizeRule("m", "mapReduce", 0)),
+                contextFile,
+                "file",
+                largeSource(3000),
+                anyHeader());
+
+        final List<String> infos = capturingLog.getCapturedInfos();
+        final long mapChunks =
+                infos.stream().filter(m -> m.contains("summarized (")).count();
+        final boolean hasRound1 = infos.stream().anyMatch(m -> m.contains("reduce round 1:"));
+        final boolean hasRound2 = infos.stream().anyMatch(m -> m.contains("reduce round 2:"));
+
+        // Whole file mapped (many chunks) and the reduce ran in at least two rounds (hierarchical).
+        assertThat(mapChunks > MIN_CHUNKS_FOR_TWO_REDUCE_ROUNDS, is(true));
+        assertThat(hasRound1, is(true));
+        assertThat(hasRound2, is(true));
+        // More provider calls than a single-level reduce (chunks + 1) would make.
+        assertThat(calls.get() > mapChunks + 1, is(true));
+        assertThat(result.body(), is(equalTo("PARTIAL")));
+    }
+
+    @Test
+    public void onOversize_sample_singleCallOnTrimmedHead() throws Exception {
+        final Path contextFile = Files.createTempFile("Huge", ".java");
+        final AtomicInteger calls = new AtomicInteger();
+        final AiGenerationProvider provider = request -> {
+            calls.incrementAndGet();
+            return "SAMPLED";
+        };
+        final AiFieldGenerationSupport support = supportWith(provider, "m");
+
+        final AiGenerationResult result = support.processFieldGenerations(
+                Collections.singletonList(oversizeRule("m", "sample", 0)),
+                contextFile,
+                "file",
+                largeSource(500),
+                anyHeader());
+
+        assertThat(calls.get(), is(equalTo(1)));
+        assertThat(result.body(), is(equalTo("SAMPLED")));
+    }
+
+    private static AiMdHeader anyHeader() {
+        return new AiMdHeader(
+                "Huge.java",
+                "1.0",
+                "ABCD1234",
+                "2026-01-01T00:00:00Z",
+                "2026-01-01T00:01:00Z",
+                "0.1.0",
+                "0.0.0",
+                AiMdHeaderCodec.NODE_TYPE_FILE);
+    }
+    // </editor-fold>
 }
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderDefaultTimingsTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderDefaultTimingsTest.java
new file mode 100644
index 0000000..b63cf2d
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationProviderDefaultTimingsTest.java
@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.provider;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import java.nio.file.Paths;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiGenerationRequest;
+import net.ladenthin.maven.llamacpp.aiindex.document.AiMdHeader;
+import org.junit.jupiter.api.Test;
+
+public class AiGenerationProviderDefaultTimingsTest {
+
+    private static final AiMdHeader HEADER = new AiMdHeader(
+            "Foo.java", "1.0", "C", "2026-01-01T00:00:00Z", "2026-01-01T00:00:10Z", "0.1.0", "1.0.0", "file");
+
+    @Test
+    public void defaultGenerateWithTimings_delegatesToGenerateWithZeroRates() throws Exception {
+        // A provider that implements only generate() inherits the interface default, which must return the
+        // generated text with zero timings (no measurement available).
+        final AiGenerationProvider provider = request -> "TEXT";
+        final AiGenerationTimings timings =
+                provider.generateWithTimings(new AiGenerationRequest("summary", Paths.get("Foo.java"), "src", HEADER));
+
+        assertThat(timings.text(), is("TEXT"));
+        assertThat(timings.promptTokens(), is(0));
+        assertThat(timings.prefillTokensPerSecond(), is(0.0d));
+        assertThat(timings.predictedTokens(), is(0));
+        assertThat(timings.decodeTokensPerSecond(), is(0.0d));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimingsTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimingsTest.java
new file mode 100644
index 0000000..9df4ec4
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/AiGenerationTimingsTest.java
@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.provider;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class AiGenerationTimingsTest {
+
+    @Test
+    public void accessorsReturnConstructorValues() {
+        final AiGenerationTimings t = new AiGenerationTimings("summary", 1500, 900.0d, 64, 45.0d);
+        assertThat(t.text(), is("summary"));
+        assertThat(t.promptTokens(), is(1500));
+        assertThat(t.prefillTokensPerSecond(), is(900.0d));
+        assertThat(t.predictedTokens(), is(64));
+        assertThat(t.decodeTokensPerSecond(), is(45.0d));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProviderTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProviderTest.java
index 50fc200..9bb0b80 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProviderTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/LlamaCppJniAiGenerationProviderTest.java
@@ -25,20 +25,29 @@ public class LlamaCppJniAiGenerationProviderTest {
             .toAbsolutePath()
             .toString();
 
-    // <editor-fold defaultstate="collapsed" desc="generate">
-    @Test
-    public void generate_realProvider_returnsNonEmptyResponse() throws Exception {
-        // arrange — skip if native lib is unavailable or model is missing
+    private static final AiMdHeader HEADER = new AiMdHeader(
+            "Test.java",
+            AiMdHeaderCodec.HEADER_VERSION_1_0,
+            "00000000",
+            "2026-03-18T00:00:00Z",
+            "2026-03-18T00:00:00Z",
+            "0.1.0-SNAPSHOT",
+            "0.0.0",
+            AiMdHeaderCodec.NODE_TYPE_FILE);
+
+    private static void assumeNativeAvailable() {
         Assumptions.assumeTrue(
                 Boolean.getBoolean("runNativeLlamaTests"),
                 "Native llama test disabled. Enable with -DrunNativeLlamaTests=true");
         Assumptions.assumeTrue(Files.exists(Paths.get(MODEL_PATH)), "Model file missing: " + MODEL_PATH);
+    }
 
-        final LlamaCppJniConfig config = new LlamaCppJniConfig(
+    private static LlamaCppJniConfig config(final int contextSize, final int maxOutputTokens) {
+        return new LlamaCppJniConfig(
                 null,
                 MODEL_PATH,
-                32768,
-                128,
+                contextSize,
+                maxOutputTokens,
                 0.15f,
                 8,
                 AiGenerationConfig.DEFAULT_TOP_P,
@@ -61,17 +70,17 @@ public void generate_realProvider_returnsNonEmptyResponse() throws Exception {
                 AiGenerationConfig.DEFAULT_DRY_PENALTY_LAST_N,
                 Collections.emptyList(),
                 Collections.emptyList());
-        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
+    }
+
+    private static AiGenerationRequest request(final String source) {
+        return new AiGenerationRequest(CommonTestFixtures.PROMPT_KEY_FILE_BODY, Paths.get("Test.java"), source, HEADER);
+    }
 
-        final AiMdHeader header = new AiMdHeader(
-                "Test.java",
-                AiMdHeaderCodec.HEADER_VERSION_1_0,
-                "00000000",
-                "2026-03-18T00:00:00Z",
-                "2026-03-18T00:00:00Z",
-                "0.1.0-SNAPSHOT",
-                "0.0.0",
-                AiMdHeaderCodec.NODE_TYPE_FILE);
+    // <editor-fold defaultstate="collapsed" desc="generate">
+    @Test
+    public void generate_realProvider_returnsNonEmptyResponse() throws Exception {
+        assumeNativeAvailable();
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
         final String source = "package com.example;\n" + "\n"
                 + "public class Test {\n"
                 + "\n"
@@ -80,17 +89,43 @@ public void generate_realProvider_returnsNonEmptyResponse() throws Exception {
                 + "    }\n"
                 + "}\n";
 
-        final AiGenerationRequest bodyRequest = new AiGenerationRequest(
-                CommonTestFixtures.PROMPT_KEY_FILE_BODY, Paths.get("Test.java"), source, header);
-
-        // act
-        try (LlamaCppJniAiGenerationProvider provider = new LlamaCppJniAiGenerationProvider(config, promptSupport)) {
-            final String body = provider.generate(bodyRequest);
-
-            // assert
+        try (LlamaCppJniAiGenerationProvider provider =
+                new LlamaCppJniAiGenerationProvider(config(32768, 128), promptSupport)) {
+            final String body = provider.generate(request(source));
             assertThat(body, is(notNullValue()));
             assertThat(body.trim().isEmpty(), is(false));
         }
     }
     // </editor-fold>
+
+    // <editor-fold defaultstate="collapsed" desc="generateWithTimings">
+    @Test
+    public void generateWithTimings_realProvider_reportsEngineTimingsThatScaleWithPromptSize() throws Exception {
+        assumeNativeAvailable();
+        final AiPromptSupport promptSupport = new AiPromptSupport(CommonTestFixtures.createFilePromptDefinitions());
+        final StringBuilder large = new StringBuilder("package com.example;\npublic class Big {\n");
+        for (int i = 0; i < 120; i++) {
+            large.append("    public int field")
+                    .append(i)
+                    .append(" = compute(")
+                    .append(i)
+                    .append(");\n");
+        }
+        large.append("}\n");
+
+        try (LlamaCppJniAiGenerationProvider provider =
+                new LlamaCppJniAiGenerationProvider(config(4096, 16), promptSupport)) {
+            final AiGenerationTimings small = provider.generateWithTimings(request("class A {}"));
+            final AiGenerationTimings big = provider.generateWithTimings(request(large.toString()));
+
+            // Real engine timings (not zero-rate default), so the plan gets exact throughput.
+            assertThat(small.prefillTokensPerSecond() > 0.0d, is(true));
+            assertThat(small.decodeTokensPerSecond() > 0.0d, is(true));
+            assertThat(small.promptTokens() > 0, is(true));
+            // A clearly larger, distinct prompt processes more prompt tokens -> proves it is the real
+            // generation path (not a discarded/zero-timings one).
+            assertThat(big.promptTokens() > small.promptTokens(), is(true));
+        }
+    }
+    // </editor-fold>
 }
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProviderTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProviderTest.java
index 5d1843b..602f851 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProviderTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/provider/MockAiGenerationProviderTest.java
@@ -38,4 +38,17 @@ public void generateFallsBackToFullPathWhenFileNameNull() throws IOException {
         AiGenerationRequest request = new AiGenerationRequest("summary", root, "src", HEADER);
         assertThat(provider.generate(request), is("Mock summary for " + root));
     }
+
+    @Test
+    public void generateWithTimings_reportsDeterministicSyntheticTimings() throws IOException {
+        // 16 chars of source / 4 chars-per-token -> 4 mock prompt tokens; positive synthetic rates so a
+        // calibrate run works without a real model.
+        final AiGenerationRequest request =
+                new AiGenerationRequest("summary", Paths.get("Foo.java"), "0123456789012345", HEADER);
+        final AiGenerationTimings timings = provider.generateWithTimings(request);
+        assertThat(timings.text(), is("Mock summary for Foo.java"));
+        assertThat(timings.promptTokens(), is(4));
+        assertThat(timings.prefillTokensPerSecond() > 0.0d, is(true));
+        assertThat(timings.decodeTokensPerSecond() > 0.0d, is(true));
+    }
 }
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummaryTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummaryTest.java
new file mode 100644
index 0000000..34ecbfa
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiDeterministicSummaryTest.java
@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.support;
+
+import static org.hamcrest.CoreMatchers.containsString;
+import static org.hamcrest.CoreMatchers.not;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import org.junit.jupiter.api.Test;
+
+public class AiDeterministicSummaryTest {
+
+    @Test
+    public void emptySource_metadataOnly_zeroCounts() {
+        final String body = AiDeterministicSummary.body("", "Empty.java", 5);
+        assertThat(body, containsString("`Empty.java`"));
+        assertThat(body, containsString("0 chars, 0 lines"));
+        assertThat(body, not(containsString("```")));
+    }
+
+    @Test
+    public void sampleLinesZero_metadataOnly() {
+        final String body = AiDeterministicSummary.body("a\nb\n", "F.java", 0);
+        assertThat(body, containsString("4 chars, 2 lines"));
+        assertThat(body, not(containsString("```")));
+    }
+
+    @Test
+    public void smallFile_showsAllContentOnce() {
+        // 3 lines <= 2*5 -> a single "Content" block with every line, no First/Last split.
+        final String body = AiDeterministicSummary.body("L1\nL2\nL3", "S.java", 5);
+        assertThat(body, containsString("8 chars, 3 lines"));
+        assertThat(body, containsString("Content:"));
+        assertThat(body, containsString("L1"));
+        assertThat(body, containsString("L3"));
+        assertThat(body, not(containsString("First")));
+    }
+
+    @Test
+    public void largeFile_showsHeadAndTailOnly() {
+        // 10 lines > 2*2 -> First 2 + Last 2; the middle (ln5) is omitted.
+        final String body =
+                AiDeterministicSummary.body("ln0\nln1\nln2\nln3\nln4\nln5\nln6\nln7\nln8\nln9", "Big.java", 2);
+        assertThat(body, containsString("First 2 lines:"));
+        assertThat(body, containsString("Last 2 lines:"));
+        assertThat(body, containsString("ln0"));
+        assertThat(body, containsString("ln1"));
+        assertThat(body, containsString("ln8"));
+        assertThat(body, containsString("ln9"));
+        assertThat(body, not(containsString("ln5")));
+    }
+
+    @Test
+    public void exactlyDoubleSampleLines_stillShowsContentNotHeadTail() {
+        // lines == 2*sampleLines is the boundary: <= keeps one "Content" block (not First/Last).
+        final String body = AiDeterministicSummary.body("a\nb\nc\nd", "B.java", 2);
+        assertThat(body, containsString("Content:"));
+        assertThat(body, not(containsString("First")));
+    }
+
+    @Test
+    public void lineCount_handlesTrailingNewlineAndNoTrailing() {
+        assertThat(AiDeterministicSummary.body("a", "f", 0), containsString("1 lines"));
+        assertThat(AiDeterministicSummary.body("a\n", "f", 0), containsString("1 lines"));
+        assertThat(AiDeterministicSummary.body("a\nb", "f", 0), containsString("2 lines"));
+    }
+
+    @Test
+    public void charCountReflectsSourceLength() {
+        assertThat(AiDeterministicSummary.body("abcde", "f", 0), containsString("5 chars"));
+    }
+}
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimatorTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimatorTest.java
index 26d3b27..e05a926 100644
--- a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimatorTest.java
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiGenerationTimeEstimatorTest.java
@@ -55,6 +55,44 @@ public void estimateSeconds_defaultOverload_usesDefaultExpectedOutputTokens() {
     }
     // </editor-fold>
 
+    // <editor-fold defaultstate="collapsed" desc="estimateSecondsCalibrated">
+    @Test
+    public void calibrated_usesLinearMeasuredThroughput() {
+        // sourceChars 4800 / cpt 4.8 = 1000 + 700 template = 1700 prompt tokens.
+        // (1700/1000 prefill + 800/100 decode) = 9.7 s; ×1.15 margin -> 11 s.
+        assertThat(estimator.estimateSecondsCalibrated(4800, 800, 1000.0d, 100.0d, 4.8d), is(11L));
+    }
+
+    @Test
+    public void calibrated_zeroPrefillRate_fallsBackToBuiltInModel() {
+        assertThat(
+                estimator.estimateSecondsCalibrated(4800, 800, 0.0d, 100.0d, 4.8d),
+                is(estimator.estimateSeconds(4800, 800)));
+    }
+
+    @Test
+    public void calibrated_zeroDecodeRate_fallsBackToBuiltInModel() {
+        assertThat(
+                estimator.estimateSecondsCalibrated(4800, 800, 1000.0d, 0.0d, 4.8d),
+                is(estimator.estimateSeconds(4800, 800)));
+    }
+
+    @Test
+    public void calibrated_zeroCharsPerToken_usesDefaultEstimationRate() {
+        assertThat(
+                estimator.estimateSecondsCalibrated(4800, 800, 1000.0d, 100.0d, 0.0d),
+                is(estimator.estimateSecondsCalibrated(4800, 800, 1000.0d, 100.0d, 4.8d)));
+    }
+
+    @Test
+    public void calibrated_defaultOverload_usesDefaultExpectedOutputTokens() {
+        assertThat(
+                estimator.estimateSecondsCalibrated(4800, 1000.0d, 100.0d, 4.8d),
+                is(estimator.estimateSecondsCalibrated(
+                        4800, AiGenerationTimeEstimator.DEFAULT_EXPECTED_OUTPUT_TOKENS, 1000.0d, 100.0d, 4.8d)));
+    }
+    // </editor-fold>
+
     // <editor-fold defaultstate="collapsed" desc="formatDuration">
     @Test
     public void formatDuration_belowThreshold_rendersSeconds() {
diff --git a/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunkerTest.java b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunkerTest.java
new file mode 100644
index 0000000..21d5895
--- /dev/null
+++ b/src/test/java/net/ladenthin/maven/llamacpp/aiindex/support/AiSourceChunkerTest.java
@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: Apache-2.0
+package net.ladenthin.maven.llamacpp.aiindex.support;
+
+import static org.hamcrest.CoreMatchers.is;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.Arrays;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+public class AiSourceChunkerTest {
+
+    @Test
+    public void maxCharsBelowOne_throws() {
+        assertThrows(IllegalArgumentException.class, () -> AiSourceChunker.chunk("abc", 0, 0, 0));
+    }
+
+    @Test
+    public void emptySource_returnsEmptyList() {
+        assertThat(AiSourceChunker.chunk("", 10, 0, 0), is(Arrays.asList()));
+    }
+
+    @Test
+    public void sourceFitsInOneChunk() {
+        assertThat(AiSourceChunker.chunk("abc", 10, 0, 0), is(Arrays.asList("abc")));
+    }
+
+    @Test
+    public void splitsAtLineBoundaries() {
+        // "L1\nL2\nL3\n" with maxChars 4 -> each chunk ends at a newline; rejoined == source.
+        final List<String> chunks = AiSourceChunker.chunk("L1\nL2\nL3\n", 4, 0, 0);
+        assertThat(chunks, is(Arrays.asList("L1\n", "L2\n", "L3\n")));
+        assertThat(String.join("", chunks), is("L1\nL2\nL3\n"));
+    }
+
+    @Test
+    public void hardCutsWhenNoNewlineInWindow() {
+        // No newline anywhere -> hard cut at maxChars.
+        assertThat(AiSourceChunker.chunk("ABCDEFGH", 3, 0, 0), is(Arrays.asList("ABC", "DEF", "GH")));
+    }
+
+    @Test
+    public void overlapIsClampedAndProducesOverlappingChunks() {
+        // overlap 100 with maxChars 4 -> clamped to 3; consecutive chunks share 3 chars.
+        final List<String> chunks = AiSourceChunker.chunk("ABCDEFGH", 4, 100, 0);
+        assertThat(chunks, is(Arrays.asList("ABCD", "BCDE", "CDEF", "DEFG", "EFGH")));
+    }
+
+    @Test
+    public void maxChunksZero_returnsAll() {
+        assertThat(AiSourceChunker.chunk("ABCDEFGHIJ", 2, 0, 0), is(Arrays.asList("AB", "CD", "EF", "GH", "IJ")));
+    }
+
+    @Test
+    public void maxChunksAtOrAboveCount_returnsAll() {
+        assertThat(AiSourceChunker.chunk("ABCDEFGHIJ", 2, 0, 10), is(Arrays.asList("AB", "CD", "EF", "GH", "IJ")));
+    }
+
+    @Test
+    public void maxChunksOne_keepsTheFirst() {
+        assertThat(AiSourceChunker.chunk("ABCDEFGHIJ", 2, 0, 1), is(Arrays.asList("AB")));
+    }
+
+    @Test
+    public void maxChunksSamplesFirstSpreadAndLast() {
+        // 5 chunks, cap 3 -> indices round(i*4/2) = 0,2,4 -> head/middle/tail.
+        assertThat(AiSourceChunker.chunk("ABCDEFGHIJ", 2, 0, 3), is(Arrays.asList("AB", "EF", "IJ")));
+    }
+
+    @Test
+    public void maxChunksUsesRoundingNotFloorForSpread() {
+        // 4 chunks, cap 3 -> indices round(i*3/2) = 0, round(1.5)=2, 3 -> AB, EF, GH (floor would pick CD).
+        assertThat(AiSourceChunker.chunk("ABCDEFGH", 2, 0, 3), is(Arrays.asList("AB", "EF", "GH")));
+    }
+}