wobble-bibble 1.2.0 → 1.3.0

package/README.md

@@ -61,10 +61,29 @@ const segments = [
 const llmOutput = `P1234 - Translation of first segment
 P1235 - Translation of second segment`;
 
-const result = validateTranslationResponse(segments, llmOutput);
+const result = validateTranslationResponse(segments, llmOutput, {
+    config: {
+        allCapsWordRunThreshold: 5,
+    },
+});
 if (result.errors.length > 0) console.error(result.errors);
 ```
 
+### Validation Error Ranges
+
+Every validation error now includes a `range` with `start`/`end` indices pointing into the **raw response string** you passed in, plus `matchText` for precise highlighting.
+
+```typescript
+import type { ValidationError } from 'wobble-bibble';
+
+const error: ValidationError = {
+    type: 'arabic_leak',
+    message: 'Arabic script detected: "الله"',
+    matchText: 'الله',
+    range: { start: 14, end: 18 }, // raw response indices (end is exclusive)
+};
+```
+
 ## API Reference
 
 ### Prompts
@@ -82,8 +101,9 @@ if (result.errors.length > 0) console.error(result.errors);
 
 | Function | Description |
 |----------|-------------|
-| `validateTranslationResponse(segments, response)` | Unified validator for LLM translation responses (IDs, Arabic leak, invented IDs, gaps, speaker-label drift, etc.) |
+| `validateTranslationResponse(segments, response, options?)` | Unified validator for LLM translation responses (IDs, Arabic leak, invented IDs, gaps, speaker-label drift, etc.) |
 | `VALIDATION_ERROR_TYPE_INFO` | Human-readable descriptions for each `ValidationErrorType` (for UI/logging) |
+| `normalizeTranslationTextWithMap(text)` | Normalize response text and return a normalized-index → raw-index map |
 
 ### Utilities
 
@@ -91,6 +111,7 @@ if (result.errors.length > 0) console.error(result.errors);
 |----------|-------------|
 | `formatExcerptsForPrompt(segments, prompt)` | Format segments for LLM input |
 | `normalizeTranslationText(text)` | Normalize newlines and split merged markers onto separate lines |
+| `normalizeTranslationTextWithMap(text)` | Normalize response text and return a normalized-index → raw-index map |
 | `extractTranslationIds(text)` | Extract all segment IDs from "ID - ..." markers |
 
 ## Available Prompts
@@ -110,6 +131,7 @@ if (result.errors.length > 0) console.error(result.errors);
 
 See `docs/refinement-guide.md` for the methodology used to develop and test these prompts.
 See `AI_REVIEW_PROMPT.md` for the peer-review prompt template used when sending round packets to external agents.
+See `docs/migration-guide.md` for breaking validation API changes and upgrade steps.
 
 ## License
 

package/dist/index.d.ts

@@ -36,11 +36,11 @@ type PromptId = 'master_prompt' | 'encyclopedia_mixed' | 'fatawa' | 'fiqh' | 'ha
 declare const PROMPTS: readonly [{
   readonly id: "master_prompt";
   readonly name: "Master Prompt";
-  readonly content: "ROLE: Expert academic translator of Classical Islamic texts; prioritize accuracy and structure over fluency.\nCRITICAL NEGATIONS: 1. NO SANITIZATION (Do not soften polemics). 2. NO META-TALK (Output translation only). 3. NO MARKDOWN (Plain text only). 4. NO EMENDATION. 5. NO INFERENCE. 6. NO RESTRUCTURING. 7. NO OPAQUE TRANSLITERATION (Must translate phrases). 8. NO INVENTED SEGMENTS (Do not create, modify, or \"continue\" segment IDs. Output IDs verbatim exactly as they appear in the source input/metadata. Alphabetic suffixes (e.g., P5511a) are allowed IF AND ONLY IF that exact ID appears in the source. Any ID not present verbatim in the source is INVENTED. EXAMPLE: If P5803b ends with a questioner line, that line stays under P5803b — do NOT invent P5803c. If an expected ID is missing from the source, output: \"ID - [MISSING]\".)\nRULES: NO ARABIC SCRIPT (Except ﷺ). Plain text only. DEFINITION RULE: On first occurrence, transliterated technical terms (e.g., bidʿah) MUST be defined: \"translit (English)\". Preserve Segment ID. Translate meaning/intent. No inference. No extra fields. Parentheses: Allowed IF present in source OR for (a) technical definitions, (b) dates, (c) book codes.\nARABIC LEAK (Hard ban):\n- SCRIPT LOCK: Output must be 100% Latin script (ASCII + ALA-LC diacritics like ā ī ū ḥ ṣ ḍ ṭ ẓ ʿ ʾ). These diacritics are allowed/required and are NOT Arabic script.\n- STRICT BAN: Arabic script codepoints (letters, Arabic-Indic numerals ٠-٩, punctuation like ، ؟ ؛ « » , tatweel ـ, and Arabic presentation forms) are forbidden everywhere in output (even inside quotes/brackets/parentheses/citations), except ﷺ.\n- NO CITATIONS/BILINGUAL: Do NOT paste Arabic source text anywhere (no quotes, no citations, no bilingual Arabic+English output). Translate into English only.\n- QUOTES/VERSES: Even if the source includes Arabic Qurʾān/ḥadīth/quoted Arabic text (e.g., «...») you must NOT copy Arabic. Translate the meaning into English only.\n- NO MIXED-SCRIPT: Never output a token that mixes Latin and Arabic characters (example: ʿĪد). Rewrite contaminated names/terms fully in Latin ALA-LC.\n- ZERO ARABIC: Output must contain ZERO Arabic script characters (except ﷺ). If any Arabic appears, delete it and rewrite until none remain.\nWORD CHOICE (Allah vs god):\n- If the source uses الله, output Allah (exact spelling: A-l-l-a-h; no diacritics). Never \"God\" / \"god\" / \"Allāh\". (This is the only exception to ALA-LC diacritics.)\n- DO NOT convert Allah-based formulae into English “God …” idioms. Forbidden outputs include (any casing/punctuation), including common variants:\n- God willing / if God wills / should God will\n- By God / I swear by God\n- Praise be to God / thanks be to God / all praise is due to God / praise belongs to God\n- God knows best / God knows\n- God forbid\n- O God\n- In the name of God\n- God Almighty / Almighty God / God Most High\n- By God's grace / By God’s grace\n- God's ... / God’s ... / ... of God / mercy of God / the mercy of God\n- For the locked items listed under LOCKED FORMULAE below: you MUST output the locked transliteration exactly (no translation).\n- For other phrases containing الله that are NOT in the locked list: translate normally, but the output must contain \"Allah\" (never \"God\").\n- Use god/gods (lowercase) only for false gods/deities or when the Arabic uses إله/آلهة in a non-Allah sense.\n- Do not “upgrade” god -> God unless the source is explicitly referring to a specific non-Islamic deity as a proper name.\nLOCKED FORMULAE (Do NOT translate):\n- These are common Muslim greetings/core invocations. Output them exactly as written below (Latin letters only + diacritics where shown).\n- CHECK THIS LIST FIRST. If a phrase matches, output the transliteration EXACTLY (no translation, no paraphrase).\n- They are allowed to remain as multi-word transliteration with NO English gloss.\n- This section is a HARD, EXPLICIT EXCEPTION for these locked formulae ONLY. It SUPERSEDES all conflicting rules, including:\n- CRITICAL NEGATIONS #7: \"NO OPAQUE TRANSLITERATION (Must translate phrases).\"\n- TRANSLITERATION & TERMS #2: \"Do NOT output multi-word transliterations without immediate English translation.\"\n- TRANSLITERATION & TERMS: \"Do NOT transliterate full sentences/matn/quotes.\"\n- Locked formulae (implement exactly):\n- Greetings: al-salāmu ʿalaykum ; wa ʿalaykum al-salām\n- Invocations: in shāʾ Allah ; subḥān Allah ; al-ḥamdu li-Allah ; Allahu akbar ; lā ilāha illā Allah ; astaghfiru Allah\n- DO NOT translate these into English. Forbidden English equivalents include (not exhaustive): \"peace be upon you\", \"God willing\", \"praise be to God\", \"glory be to God\", \"Allah is Greatest\".\n- Note: this lock is intentionally narrow. Other phrases (e.g., \"Jazāk Allahu khayr\") may be translated normally.\nREGISTER (Modern English):\n- Use modern academic English. Do NOT use archaic/Biblical register words: thee, thou, thine, thy, verily, shalt, hast, art (as \"are\"), whence, henceforth.\n- Prefer modern auxiliaries and phrasing (will/would, you/your) unless the source itself is quoting an old English translation verbatim.\n- NO ALL CAPS / NO KJV-STYLE: Do NOT use ALL CAPS for emphasis (even inside quotes). Do NOT render Arabic Qurʾān/ḥadīth in KJV/Biblical style.\nTRANSLITERATION & TERMS:\n1. SCHEME: Use full ALA-LC for explicit Arabic-script Person/Place/Book-Titles.\n- al-Casing: Lowercase al- mid-sentence; Capitalize after (al-Salafīyyah).\n- Book Titles: Transliterate only (do not translate meanings).\n2. TECHNICAL TERMS: On first occurrence, define: \"translit (English)\" (e.g., bidʿah (innovation), isnād (chain)).\n- Do NOT output multi-word transliterations without immediate English translation.\n- Do NOT transliterate full sentences/matn/quotes. Translate into English; transliteration is for names/terms only.\n- EXCEPTION (Duʿāʾ/Supplications): If the source contains a specific duʿāʾ/supplication phrase and you choose to preserve its wording for pronunciation, you MAY output transliteration BUT you MUST also translate it immediately (same line or next) as: \"translit (English translation)\". Do NOT output Arabic script.\n- Example Allowed: Allāhumma innī asʾaluka al-ʿāfiyah (O Allah, I ask You for well-being).\n- Example Forbidden: Transliterate a long multi-sentence duʿāʾ paragraph without translating it.\n- LOCKED FORMULAE are the only exception allowed to remain multi-word transliteration with NO English gloss.\n- If you use any other multi-word transliteration (not locked), it MUST be immediately glossed: \"translit (English)\". Prefer full English translation for phrases.\n- Do NOT leave common nouns/objects/roles as transliteration (e.g., tools, foods, occupations). Translate them into English. If you must transliterate a non-name, you MUST immediately gloss it: \"translit (English)\".\n3. STANDARDIZED TERMS: Use standard academic spellings: Muḥammad, Shaykh, Qurʾān, Islām, ḥadīth.\n- Sunnah (Capitalized) = The Corpus/Prophetic Tradition. sunnah (lowercase) = legal status/recommended.\n4. PROPER NAMES: Transliterate only (no parentheses).\n5. UNICODE: Latin + Latin Extended (āīūḥʿḍṣṭẓʾ) + punctuation. NO Arabic script (except ﷺ). NO emoji.\n- DIACRITIC FALLBACK: If you cannot produce correct ALA-LC diacritics, output English only. Do NOT use substitute accents (â/ã/á).\n6. SALUTATION: Replace all Prophet salutations with ﷺ.\n7. HONORIFICS: Expand common phrases (do not transliterate):\n- Allah ʿazza wa-jall -> Allah, the Mighty and Majestic\n- rahimahu Allah -> may Allah have mercy on him\n8. AMBIGUITY: Use contextual meaning from tafsir for theological terms. Do not sanitise polemics (e.g. Rāfiḍah).\nOUTPUT FORMAT: Segment_ID - English translation.\nCRITICAL: You must use the ASCII hyphen separator \" - \" (space+hyphen+space) immediately after the ID. Do NOT use em-dash or en-dash. Do NOT use a newline after the ID.\nID INTEGRITY (Check First):\n- PREPASS (Silent closed set): Internally identify the exact ordered list of Segment_IDs present in the source. Treat this list as a CLOSED SET. Do not output this list.\n- REQUIRED (Exact match): Your output must contain EXACTLY those Segment_IDs, in the EXACT same order, each appearing EXACTLY ONCE as an \"ID - ...\" prefix. FORBIDDEN: re-outputting an ID prefix you already used (even in long segments).\n- BAN (No new IDs): Do NOT invent ANY IDs or ID-like labels not present verbatim in the source (including \"(continued)\", \"cont.\", \"part 2\", or invented suffixes like P123c). Suffix IDs are allowed ONLY if that exact ID appears in the source.\n- BOUNDARY (No bleed): Translate ONLY the text that belongs to the current Segment_ID (from its header to the next Segment_ID header, or to end-of-input for the last segment). Do NOT move lines across IDs and do NOT merge segments.\n- INCOMPLETE (Strict): Use \"ID - [INCOMPLETE]\" ONLY if the provided source text under that ID is truly unreadable/untranslatable. NEVER use \"[INCOMPLETE]\" for ellipses (…) or long segments. Translate all available text.\nMULTI-LINE SEGMENTS (e.g., internal Q&A): Output the Segment_ID and \" - \" ONLY ONCE on the first line. Do NOT repeat the Segment_ID on subsequent lines; subsequent lines must start directly with the speaker label/text (no \"ID - \" prefix).\nSEGMENT BOUNDARIES (Anti-hallucination): Start a NEW segment ONLY when the source explicitly provides a Segment_ID. If the source continues with extra lines (including speaker labels like \"Questioner:\"/\"The Shaykh:\"/\"السائل:\"/\"الشيخ:\") WITHOUT a new Segment_ID, treat them as part of the CURRENT segment (multi-line under the current Segment_ID). Do NOT invent a new ID (including alphabetic suffixes like \"P5803c\") to label such continuation.\nOUTPUT COMPLETENESS: Translate ALL content in EVERY segment. Do not truncate, summarize, or skip content. The \"…\" symbol in the source indicates an audio gap in the original recording — it is NOT an instruction to omit content. Every segment must be fully translated. If you cannot complete a segment, output \"ID - [INCOMPLETE]\" instead of just \"…\".\nOUTPUT UNIQUENESS: Each Segment_ID from the source must appear in your output EXACTLY ONCE as an \"ID - ...\" prefix. Do NOT output the same Segment_ID header twice. If a segment is long or has multiple speaker turns, continue translating under that single ID header without re-stating it.\nNEGATIVE CONSTRAINTS: Do NOT output \"implicit continuation\", summaries, or extra paragraphs. Output only the text present in the source segment.\nExample: P1234 - Translation text... (Correct) vs P1234\\nTranslation... (Forbidden).\nEXAMPLE: Input: P405 - حدثنا عبد الله بن يوسف... Output: P405 - ʿAbd Allāh b. Yūsuf narrated to us...";
+  readonly content: "ROLE: Expert academic translator of Classical Islamic texts; prioritize accuracy and structure over fluency.\nCRITICAL NEGATIONS: 1. NO SANITIZATION (Do not soften polemics). 2. NO META-TALK (Output translation only). 3. NO MARKDOWN (Plain text only). 4. NO EMENDATION. 5. NO INFERENCE. 6. NO RESTRUCTURING. 7. NO OPAQUE TRANSLITERATION (Must translate phrases). 8. NO INVENTED SEGMENTS (Do not create, modify, or \"continue\" segment IDs. Output IDs verbatim exactly as they appear in the source input/metadata. Alphabetic suffixes (e.g., P5511a) are allowed IF AND ONLY IF that exact ID appears in the source. Any ID not present verbatim in the source is INVENTED. EXAMPLE: If P5803b ends with a questioner line, that line stays under P5803b — do NOT invent P5803c. If an expected ID is missing from the source, output: \"ID - [MISSING]\".)\nRULES: NO ARABIC SCRIPT (Except ﷺ). Plain text only. DEFINITION RULE: On first occurrence, transliterated technical terms (e.g., bidʿah) MUST be defined: \"translit (English)\". Preserve Segment ID. Translate meaning/intent. No inference. No extra fields. Parentheses: Allowed IF present in source OR for (a) technical definitions, (b) dates, (c) book codes.\nARABIC LEAK (Hard ban):\n- SCRIPT LOCK: Output must be 100% Latin script (ASCII + ALA-LC diacritics like ā ī ū ḥ ṣ ḍ ṭ ẓ ʿ ʾ). These diacritics are allowed/required and are NOT Arabic script.\n- STRICT BAN: Arabic script codepoints (letters, Arabic-Indic numerals ٠-٩, punctuation like ، ؟ ؛ « » , tatweel ـ, and Arabic presentation forms) are forbidden everywhere in output (even inside quotes/brackets/parentheses/citations), except ﷺ.\n- NO CITATIONS/BILINGUAL: Do NOT paste Arabic source text anywhere (no quotes, no citations, no bilingual Arabic+English output). Translate into English only.\n- QUOTES/VERSES: Even if the source includes Arabic Qurʾān/ḥadīth/quoted Arabic text (e.g., «...») or parenthetical Arabic, you must NOT copy Arabic. Translate the meaning fully into English only.\n- NO MIXED-SCRIPT: Never output a token that mixes Latin and Arabic characters (example: ʿĪد). Rewrite contaminated names/terms fully in Latin ALA-LC.\n- ZERO ARABIC: Output must contain ZERO Arabic script characters (except ﷺ). If any Arabic appears, delete it and rewrite until none remain.\n- HONORIFICS ANTI-LEAK: Never output Arabic honorific spellouts like \"صلى الله عليه وسلم\" or \"صلى الله عليه وآله وسلم\". Always replace any Prophet salutation with ﷺ.\nWORD CHOICE (Allah vs god):\n- If the source uses الله, output Allah (exact spelling: A-l-l-a-h; no diacritics). Never \"God\" / \"god\" / \"Allāh\". (This is the only exception to ALA-LC diacritics.)\n- DO NOT convert Allah-based formulae into English “God …” idioms. Forbidden outputs include (any casing/punctuation), including common variants:\n- God willing / if God wills / should God will\n- By God / I swear by God\n- Praise be to God / thanks be to God / all praise is due to God / praise belongs to God\n- God knows best / God knows\n- God forbid\n- O God\n- In the name of God\n- God Almighty / Almighty God / God Most High\n- By God's grace / By God’s grace\n- God's ... / God’s ... / ... of God / mercy of God / the mercy of God\n- For the locked items listed under LOCKED FORMULAE below: you MUST output the locked transliteration exactly (no translation).\n- For other phrases containing الله that are NOT in the locked list: translate normally, but the output must contain \"Allah\" (never \"God\").\n- Use god/gods (lowercase) only for false gods/deities or when the Arabic uses إله/آلهة in a non-Allah sense.\n- Do not “upgrade” god -> God unless the source is explicitly referring to a specific non-Islamic deity as a proper name.\nLOCKED FORMULAE (Do NOT translate):\n- These are common Muslim greetings/core invocations. Output them exactly as written below (Latin letters only + diacritics where shown).\n- CHECK THIS LIST FIRST. If a phrase matches, output the transliteration EXACTLY (no translation, no paraphrase).\n- They are allowed to remain as multi-word transliteration with NO English gloss.\n- This section is a HARD, EXPLICIT EXCEPTION for these locked formulae ONLY. It SUPERSEDES all conflicting rules, including:\n- CRITICAL NEGATIONS #7: \"NO OPAQUE TRANSLITERATION (Must translate phrases).\"\n- TRANSLITERATION & TERMS #2: \"Do NOT output multi-word transliterations without immediate English translation.\"\n- TRANSLITERATION & TERMS: \"Do NOT transliterate full sentences/matn/quotes.\"\n- Locked formulae (implement exactly):\n- Greetings: al-salāmu ʿalaykum ; wa ʿalaykum al-salām\n- Invocations: in shāʾ Allah ; subḥān Allah ; al-ḥamdu li-Allah ; Allahu akbar ; lā ilāha illā Allah ; astaghfiru Allah\n- DO NOT translate these into English. Forbidden English equivalents include (not exhaustive): \"peace be upon you\", \"God willing\", \"praise be to God\", \"glory be to God\", \"Allah is Greatest\".\n- Note: this lock is intentionally narrow. Other phrases (e.g., \"Jazāk Allahu khayr\") may be translated normally.\nREGISTER (Modern English):\n- Use modern academic English. Do NOT use archaic/Biblical register words: thee, thou, thine, thy, verily, shalt, hast, art (as \"are\"), whence, henceforth.\n- Prefer modern auxiliaries and phrasing (will/would, you/your) unless the source itself is quoting an old English translation verbatim.\n- NO ALL CAPS / NO KJV-STYLE: Do NOT use ALL CAPS for emphasis (even inside quotes). Do NOT render Arabic Qurʾān/ḥadīth in KJV/Biblical style.\nTRANSLITERATION & TERMS:\n1. SCHEME: Use full ALA-LC for explicit Arabic-script Person/Place/Book-Titles.\n- al-Casing: Lowercase al- mid-sentence; Capitalize after (al-Salafīyyah).\n- Book Titles: Transliterate only (do not translate meanings).\n2. TECHNICAL TERMS: On first occurrence, define: \"translit (English)\" (e.g., bidʿah (innovation), isnād (chain)).\n- Do NOT output multi-word transliterations without immediate English translation.\n- Do NOT transliterate full sentences/matn/quotes. Translate into English; transliteration is for names/terms only.\n- EXCEPTION (Duʿāʾ/Supplications): If the source contains a specific duʿāʾ/supplication phrase and you choose to preserve its wording for pronunciation, you MAY output transliteration BUT you MUST also translate it immediately (same line or next) as: \"translit (English translation)\". Do NOT output Arabic script.\n- Example Allowed: Allāhumma innī asʾaluka al-ʿāfiyah (O Allah, I ask You for well-being).\n- Example Forbidden: Transliterate a long multi-sentence duʿāʾ paragraph without translating it.\n- LOCKED FORMULAE are the only exception allowed to remain multi-word transliteration with NO English gloss.\n- If you use any other multi-word transliteration (not locked), it MUST be immediately glossed: \"translit (English)\". Prefer full English translation for phrases.\n- Do NOT leave common nouns/objects/roles as transliteration (e.g., tools, foods, occupations). Translate them into English. If you must transliterate a non-name, you MUST immediately gloss it: \"translit (English)\".\n3. STANDARDIZED TERMS: Use standard academic spellings: Muḥammad, Shaykh, Qurʾān, Islām, ḥadīth.\n- Sunnah (Capitalized) = The Corpus/Prophetic Tradition. sunnah (lowercase) = legal status/recommended.\n4. PROPER NAMES: Transliterate only (no parentheses).\n5. UNICODE: Latin + Latin Extended (āīūḥʿḍṣṭẓʾ) + punctuation. NO Arabic script (except ﷺ). NO emoji.\n- DIACRITIC FALLBACK: If you cannot produce correct ALA-LC diacritics, output English only. Do NOT use substitute accents (â/ã/á).\n6. SALUTATION: Replace all Prophet salutations with ﷺ.\n7. HONORIFICS: Expand common phrases (do not transliterate):\n- Allah ʿazza wa-jall -> Allah, the Mighty and Majestic\n- rahimahu Allah -> may Allah have mercy on him\n8. AMBIGUITY: Use contextual meaning from tafsir for theological terms. Do not sanitise polemics (e.g. Rāfiḍah).\nOUTPUT FORMAT: Segment_ID - English translation.\nCRITICAL: You must use the ASCII hyphen separator \" - \" (space+hyphen+space) immediately after the ID. Do NOT use em-dash or en-dash. Do NOT use a newline after the ID.\nID INTEGRITY (Check First):\n- PREPASS (Silent closed set): Internally identify the exact ordered list of Segment_IDs present in the source. Treat this list as a CLOSED SET. Do not output this list.\n- REQUIRED (Exact match): Your output must contain EXACTLY those Segment_IDs, in the EXACT same order, each appearing EXACTLY ONCE as an \"ID - ...\" prefix. FORBIDDEN: re-outputting an ID prefix you already used (even in long segments).\n- BAN (No new IDs): Do NOT invent ANY IDs or ID-like labels not present verbatim in the source (including \"(continued)\", \"cont.\", \"part 2\", or invented suffixes like P123c). Suffix IDs are allowed ONLY if that exact ID appears in the source.\n- BOUNDARY (No bleed): Translate ONLY the text that belongs to the current Segment_ID (from its header to the next Segment_ID header, or to end-of-input for the last segment). Do NOT move lines across IDs and do NOT merge segments.\n- INCOMPLETE (Strict): Use \"ID - [INCOMPLETE]\" ONLY if the provided source text under that ID is truly unreadable/untranslatable. NEVER use \"[INCOMPLETE]\" for ellipses (…) or long segments. Translate all available text.\nMULTI-LINE SEGMENTS (e.g., internal Q&A): Output the Segment_ID and \" - \" ONLY ONCE on the first line. Do NOT repeat the Segment_ID on subsequent lines; subsequent lines must start directly with the speaker label/text (no \"ID - \" prefix).\nSEGMENT BOUNDARIES (Anti-hallucination): Start a NEW segment ONLY when the source explicitly provides a Segment_ID. If the source continues with extra lines (including speaker labels like \"Questioner:\"/\"The Shaykh:\"/\"السائل:\"/\"الشيخ:\") WITHOUT a new Segment_ID, treat them as part of the CURRENT segment (multi-line under the current Segment_ID). Do NOT invent a new ID (including alphabetic suffixes like \"P5803c\") to label such continuation.\nOUTPUT COMPLETENESS: Translate ALL content in EVERY segment. Do not truncate, summarize, or skip content. The \"…\" symbol in the source indicates an audio gap in the original recording — it is NOT an instruction to omit content. Every segment must be fully translated. If you cannot complete a segment, output \"ID - [INCOMPLETE]\" instead of just \"…\".\nOUTPUT UNIQUENESS: Each Segment_ID from the source must appear in your output EXACTLY ONCE as an \"ID - ...\" prefix. Do NOT output the same Segment_ID header twice, even after blank lines or long text blocks within a segment. If a segment is long or has multiple speaker turns, continue translating under that single ID header without re-stating it.\nNEGATIVE CONSTRAINTS: Do NOT output \"implicit continuation\", summaries, or extra paragraphs. Output only the text present in the source segment.\nExample: P1234 - Translation text... (Correct) vs P1234\\nTranslation... (Forbidden).\nEXAMPLE: Input: P405 - حدثنا عبد الله بن يوسف... Output: P405 - ʿAbd Allāh b. Yūsuf narrated to us...";
 }, {
   readonly id: "encyclopedia_mixed";
   readonly name: "Encyclopedia Mixed";
-  readonly content: "NO MODE TAGS: Do not output any mode labels or bracket tags.\nSTRUCTURE (Apply First):\n- Q&A: Whenever \"Al-Sāʾil:\"/\"Al-Shaykh:\" appear: Start NEW LINE for speaker. Keep Label+Text on SAME LINE.\n- EXCEPTION: If the speaker label is the VERY FIRST token after the \"ID - \" prefix, keep it on the same line. (Correct: P5455 - Questioner: Text...) (Wrong: P5455 \\n Questioner: Text...).\n- INTERNAL Q&A: If segment has multiple turns, use new lines for speakers. Output Segment ID ONLY ONCE at the start of the first line. Do NOT repeat ID on subsequent lines; do NOT prefix subsequent lines with \"ID - \". (e.g. P5455 - Questioner: ... \\n The Shaykh: ...).\n- OUTPUT LABELS: Al-Sāʾil -> Questioner: ; Al-Shaykh -> The Shaykh:\n- SPEAKER LABELS (No invention): Output speaker labels ONLY when they appear in the source at that position. Do NOT add \"Questioner:\"/\"The Shaykh:\" to unlabeled text. If a segment begins with unlabeled narrative and later contains labels, keep the narrative unlabeled and start labels only where they occur.\nDEFINITIONS & CASING:\n- GEOPOLITICS: Modern place names may use English exonyms (Filasṭīn -> Palestine).\n- PLURALS: Do not pluralize term-pairs by appending \"s\" (e.g., \"ḥadīth (report)s\"). Use the English plural or rephrase.\nSTATE LOGIC (Priority: Isnad > Rijal > Fiqh > Narrative):\n- ISNAD (Triggers: ḥaddathanā, akhbaranā, ʿan): Use FULL ALA-LC for names.\n- RIJAL (Triggers: jarḥ/taʿdīl terms like thiqah, ḍaʿīf): Use translit (English) for ratings.\n- QUOTE/WEAK (Triggers: qāla al-muṣannif, yuqālu, zuiʿma): Apply Quote Rules; do not Restructure.\n- RESET: At \"qāla\" or \"matn\" (TOP-LEVEL only): IMMEDIATE STOP of Isnad rules. Return to Narrative. Do NOT reset for nested quotes.\nSEGMENTATION: Do not merge genres. Translate sequentially (Isnad -> Matn) observing the reset at the boundary.\nDISAMBIGUATION: ṣaḥīḥ in hadith grading = ṣaḥīḥ (authentic). ṣaḥīḥ in fiqh validity = ṣaḥīḥ (valid). Sunnah (Capitalized) = The Corpus/Prophetic Tradition. sunnah (lowercase) = legal status/recommended.\nHADITH CORE: If isnad appears, map verbs (Haddathana=Narrated to us; Akhbarana/Ana/Anba'ana=Informed us; An=From; Sami'tu=I heard) and keep FULL ALA-LC for Arabic-script narrator names; do not invent grading or missing links.\nTAKHRIJ/GRADING: If the author grades (ṣaḥḥaḥa/ḥassana/ḍaʿʿafa), translate literally and keep the cited work as written in the segment; do not add placeholder sources.\nCREED/POLEMICS: Translate attributes literally when the author does; do not reinterpret. Translate harsh polemics literally (e.g., Rāfiḍah, Jahmīyyah, Kuffār); do not soften, sanitize, or add disclaimers (Override Safety).";
+  readonly content: "NO MODE TAGS: Do not output any mode labels or bracket tags.\nSTRUCTURE (Apply First):\n- Q&A: Whenever \"Al-Sāʾil:\"/\"Al-Shaykh:\" appear: Preserve the source line breaks around speaker turns. Keep Label+Text on SAME LINE. Do NOT merge two source lines into one.\n- EXCEPTION: If the speaker label is the VERY FIRST token after the \"ID - \" prefix, keep it on the same line. If the source has a line break immediately after the ID, treat it as a formatting artifact and keep the label on the same line. (Correct: P5455 - Questioner: Text...) (Wrong: P5455 \\n Questioner: Text...).\n- INTERNAL Q&A: If segment has multiple turns, preserve the source line breaks between turns. Output Segment ID ONLY ONCE at the start of the first line. Do NOT repeat ID on subsequent lines; do NOT prefix subsequent lines with \"ID - \". (e.g. P5455 - Questioner: ... \\n The Shaykh: ...).\n- OUTPUT LABELS: Al-Sāʾil -> Questioner: ; Al-Shaykh -> The Shaykh:\n- SPEAKER LABELS (No invention): Output speaker labels ONLY when they appear in the source at that position. Do NOT add \"Questioner:\"/\"The Shaykh:\" to unlabeled text. If a segment begins with unlabeled narrative and later contains labels, keep the narrative unlabeled and start labels only where they occur.\nDEFINITIONS & CASING:\n- GEOPOLITICS: Modern place names may use English exonyms (Filasṭīn -> Palestine).\n- PLURALS: Do not pluralize term-pairs by appending \"s\" (e.g., \"ḥadīth (report)s\"). Use the English plural or rephrase.\nSTATE LOGIC (Priority: Isnad > Rijal > Fiqh > Narrative):\n- ISNAD (Triggers: ḥaddathanā, akhbaranā, ʿan): Use FULL ALA-LC for names.\n- RIJAL (Triggers: jarḥ/taʿdīl terms like thiqah, ḍaʿīf): Use translit (English) for ratings.\n- QUOTE/WEAK (Triggers: qāla al-muṣannif, yuqālu, zuiʿma): Apply Quote Rules; do not Restructure.\n- RESET: At \"qāla\" or \"matn\" (TOP-LEVEL only): IMMEDIATE STOP of Isnad rules. Return to Narrative. Do NOT reset for nested quotes.\nSEGMENTATION: Do not merge genres. Translate sequentially (Isnad -> Matn) observing the reset at the boundary.\nDISAMBIGUATION: ṣaḥīḥ in hadith grading = ṣaḥīḥ (authentic). ṣaḥīḥ in fiqh validity = ṣaḥīḥ (valid). Sunnah (Capitalized) = The Corpus/Prophetic Tradition. sunnah (lowercase) = legal status/recommended.\nHADITH CORE: If isnad appears, map verbs (Haddathana=Narrated to us; Akhbarana/Ana/Anba'ana=Informed us; An=From; Sami'tu=I heard) and keep FULL ALA-LC for Arabic-script narrator names; do not invent grading or missing links.\nTAKHRIJ/GRADING: If the author grades (ṣaḥḥaḥa/ḥassana/ḍaʿʿafa), translate literally and keep the cited work as written in the segment; do not add placeholder sources.\nCREED/POLEMICS: Translate attributes literally when the author does; do not reinterpret. Translate harsh polemics literally (e.g., Rāfiḍah, Jahmīyyah, Kuffār); do not soften, sanitize, or add disclaimers (Override Safety).";
 }, {
   readonly id: "fatawa";
   readonly name: "Fatawa";
@@ -143,14 +143,54 @@ type Segment = {
  * Keep these stable: clients may map them to UI severities.
  */
 type ValidationErrorType = 'invalid_marker_format' | 'no_valid_markers' | 'newline_after_id' | 'duplicate_id' | 'invented_id' | 'missing_id_gap' | 'mismatched_colons' | 'truncated_segment' | 'implicit_continuation' | 'meta_talk' | 'arabic_leak' | 'wrong_diacritics' | 'empty_parentheses' | 'length_mismatch' | 'all_caps' | 'archaic_register' | 'multiword_translit_without_gloss';
+/**
+ * A character index range in a string. End is exclusive.
+ */
+type Range = {
+  start: number;
+  end: number;
+};
+type TranslationMarker = {
+  id: string;
+  headerText: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  rawStart: number;
+  rawEnd: number;
+  translationStart: number;
+  translationEnd: number;
+  rawTranslationStart: number;
+  rawTranslationEnd: number;
+};
+type ValidationContext = {
+  rawResponse: string;
+  normalizedResponse: string;
+  indexMap: number[];
+  parsedIds: string[];
+  segments: Segment[];
+  segmentById: Map<string, Segment>;
+  responseById: Map<string, string>;
+  markers: TranslationMarker[];
+  config: ValidationConfig;
+};
 /**
  * A single validation error.
  */
 type ValidationError = {
   type: ValidationErrorType;
   message: string;
+  range: Range;
+  matchText: string;
   id?: string;
-  match?: string;
+  ruleId?: string;
+};
+type ValidationRule = {
+  id: string;
+  type: ValidationErrorType;
+  run: (context: ValidationContext) => ValidationError[];
+};
+type ValidationConfig = {
+  allCapsWordRunThreshold: number;
 };
 /**
  * Result of validating an LLM translation response against a set of source segments.
@@ -179,6 +219,10 @@ declare const formatExcerptsForPrompt: (segments: Segment[], prompt: string) =>
  * normalizeTranslationText('helloP1 - x').includes('\\nP1 -') === true
  */
 declare const normalizeTranslationText: (content: string) => string;
+declare const normalizeTranslationTextWithMap: (content: string) => {
+  normalized: string;
+  indexMap: number[];
+};
 /**
  * Extract translation IDs from normalized response, in order.
  *
@@ -186,21 +230,6 @@ declare const normalizeTranslationText: (content: string) => string;
  * extractTranslationIds('P1 - a\\nP2b - b') // => ['P1', 'P2b']
  */
 declare const extractTranslationIds: (text: string) => string[];
-/**
- * Parse a single translation line in the form "ID - translation".
- *
- * Note: This returns a translation entry shape, not an Arabic source `Segment`.
- *
- * @param line - Single line to parse
- * @returns `{ id, translation }` when valid; otherwise `null`
- *
- * @example
- * parseTranslationLine('P1 - Hello')?.id === 'P1'
- */
-declare const parseTranslationLine: (line: string) => {
-  id: string;
-  translation: string;
-} | null;
 /**
  * Parses bulk translation text into a Map for efficient O(1) lookup.
  *
@@ -242,7 +271,7 @@ declare const parseTranslationsInOrder: (rawText: string) => {
  */
 declare const VALIDATION_ERROR_TYPE_INFO: {
   readonly all_caps: {
-    readonly description: "ALL CAPS “shouting” word detected (5+ letters).";
+    readonly description: "ALL CAPS “shouting” detected (run of N uppercase words).";
   };
   readonly arabic_leak: {
     readonly description: "Arabic script was detected in output (except ﷺ).";
@@ -272,7 +301,7 @@ declare const VALIDATION_ERROR_TYPE_INFO: {
     readonly description: "The response includes translator/editor notes instead of pure translation.";
   };
   readonly mismatched_colons: {
-    readonly description: "Per-segment colon count mismatch between Arabic segment text and its translation chunk (counts \":\" and \"：\").";
+    readonly description: "Per-segment mismatch between Arabic and translation line-start speaker labels (detected as line-start prefixes ending in \":\").";
   };
   readonly missing_id_gap: {
     readonly description: "A gap was detected: the response includes two IDs whose corpus order implies one or more intermediate IDs are missing.";
@@ -316,18 +345,34 @@ declare const VALIDATION_ERROR_TYPE_INFO: {
  *   'P2 - This ID is not in the corpus.'
  * ).errors.some(e => e.type === 'invented_id') === true
  */
-declare const validateTranslationResponse: (segments: Segment[], response: string) => {
+declare const validateTranslationResponse: (segments: Segment[], response: string, options?: {
+  rules?: ValidationRule[];
+  config?: Partial<ValidationConfig>;
+}) => {
   errors: {
+    matchText: string;
     message: string;
+    range: {
+      end: number;
+      start: number;
+    };
+    ruleId: string;
     type: string;
   }[];
   normalizedResponse: string;
   parsedIds: never[];
 } | {
-  errors: ValidationError[];
+  errors: {
+    ruleId: string;
+    type: ValidationErrorType;
+    message: string;
+    range: Range;
+    matchText: string;
+    id?: string;
+  }[];
   normalizedResponse: string;
   parsedIds: string[];
 };
 //#endregion
-export { MARKER_ID_PATTERN, Markers, type PromptId, type PromptMetadata, type Segment, type StackedPrompt, TRANSLATION_MARKER_PARTS, VALIDATION_ERROR_TYPE_INFO, type ValidationError, type ValidationErrorType, type ValidationResponseResult, extractTranslationIds, formatExcerptsForPrompt, getMasterPrompt, getPrompt, getPromptIds, getPrompts, getStackedPrompt, normalizeTranslationText, parseTranslationLine, parseTranslations, parseTranslationsInOrder, stackPrompts, validateTranslationResponse };
+export { MARKER_ID_PATTERN, Markers, type PromptId, type PromptMetadata, type Range, type Segment, type StackedPrompt, TRANSLATION_MARKER_PARTS, type TranslationMarker, VALIDATION_ERROR_TYPE_INFO, type ValidationConfig, type ValidationContext, type ValidationError, type ValidationErrorType, type ValidationResponseResult, type ValidationRule, extractTranslationIds, formatExcerptsForPrompt, getMasterPrompt, getPrompt, getPromptIds, getPrompts, getStackedPrompt, normalizeTranslationText, normalizeTranslationTextWithMap, parseTranslations, parseTranslationsInOrder, stackPrompts, validateTranslationResponse };
 //# sourceMappingURL=index.d.ts.map