wobble-bibble 1.0.3 → 1.1.0

package/README.md

@@ -51,24 +51,18 @@ const ids = getPromptIds(); // ['master_prompt', 'hadith', 'fiqh', ...]
 ### Validate LLM Output
 
 ```typescript
-import {
-    validateTranslations,
-    detectArabicScript,
-    detectNewlineAfterId,
-} from 'wobble-bibble';
+import { validateTranslationResponse } from 'wobble-bibble';
+
+const segments = [
+    { id: 'P1234', text: '... Arabic source for P1234 ...' },
+    { id: 'P1235', text: '... Arabic source for P1235 ...' },
+];
 
 const llmOutput = `P1234 - Translation of first segment
 P1235 - Translation of second segment`;
 
-// Full validation pipeline
-const result = validateTranslations(llmOutput, ['P1234', 'P1235']);
-if (!result.isValid) {
-    console.error('Error:', result.error);
-}
-
-// Individual detectors
-const arabicWarnings = detectArabicScript(llmOutput); // Soft warnings
-const newlineError = detectNewlineAfterId(llmOutput); // Hard error
+const result = validateTranslationResponse(segments, llmOutput);
+if (result.errors.length > 0) console.error(result.errors);
 ```
 
 ## API Reference
@@ -84,32 +78,20 @@ const newlineError = detectNewlineAfterId(llmOutput); // Hard error
 | `getPromptIds()` | Get list of available prompt IDs |
 | `stackPrompts(master, addon)` | Manually combine prompts |
 
-### Validation (Hard Errors)
-
-| Function | Description |
-|----------|-------------|
-| `validateTranslations(text, expectedIds)` | Full validation pipeline |
-| `validateTranslationMarkers(text)` | Check for malformed IDs (e.g., `P123$4`) |
-| `detectNewlineAfterId(text)` | Catch `P1234\nText` (Gemini bug) |
-| `detectImplicitContinuation(text)` | Catch "implicit continuation" text |
-| `detectMetaTalk(text)` | Catch "(Note:", "[Editor:" |
-| `detectDuplicateIds(ids)` | Catch same ID appearing twice |
-
-### Validation (Soft Warnings)
+### Validation
 
 | Function | Description |
 |----------|-------------|
-| `detectArabicScript(text)` | Detect Arabic characters (except ﷺ) |
-| `detectWrongDiacritics(text)` | Detect â/ã/á instead of macrons |
+| `validateTranslationResponse(segments, response)` | 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) |
 
 ### Utilities
 
 | Function | Description |
 |----------|-------------|
-| `extractTranslationIds(text)` | Extract all segment IDs from text |
-| `normalizeTranslationText(text)` | Split merged markers onto separate lines |
-| `findUnmatchedTranslationIds(ids, expected)` | Find IDs not in expected list |
 | `formatExcerptsForPrompt(segments, prompt)` | Format segments for LLM input |
+| `normalizeTranslationText(text)` | Normalize newlines and split merged markers onto separate lines |
+| `extractTranslationIds(text)` | Extract all segment IDs from "ID - ..." markers |
 
 ## Available Prompts
 
@@ -126,7 +108,8 @@ const newlineError = detectNewlineAfterId(llmOutput); // Hard error
 
 ## Prompt Development
 
-See [REFINEMENT_GUIDE.md](docs/refinement-guide.md) for the methodology used to develop and test these prompts.
+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.
 
 ## License
 

package/dist/index.d.ts

@@ -31,14 +31,43 @@ declare const TRANSLATION_MARKER_PARTS: {
  */
 declare const MARKER_ID_PATTERN: string;
 //#endregion
-//#region src/formatting.d.ts
+//#region src/types.d.ts
 /**
- * Internal segment type for formatting.
+ * A single segment (Arabic source excerpt) identified by an ID.
+ *
+ * Canonical shape (breaking change): `{ id, text }`.
+ *
+ * @example
+ * const seg: Segment = { id: 'P1', text: 'نص عربي...' };
  */
 type Segment = {
-  /** The segment ID (e.g., P1) */id: string; /** The segment text */
+  id: string;
   text: string;
 };
+/**
+ * Machine-readable error types emitted by the validator.
+ * 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 single validation error.
+ */
+type ValidationError = {
+  type: ValidationErrorType;
+  message: string;
+  id?: string;
+  match?: string;
+};
+/**
+ * Result of validating an LLM translation response against a set of source segments.
+ */
+type ValidationResponseResult = {
+  normalizedResponse: string;
+  parsedIds: string[];
+  errors: ValidationError[];
+};
+//#endregion
+//#region src/textUtils.d.ts
 /**
  * Formats excerpts for an LLM prompt by combining the prompt rules with the segment text.
  * Each segment is formatted as "ID - Text" and separated by double newlines.
@@ -48,21 +77,36 @@ type Segment = {
  * @returns Combined prompt and formatted text
  */
 declare const formatExcerptsForPrompt: (segments: Segment[], prompt: string) => string;
+/**
+ * Normalize line endings and split merged markers onto separate lines.
+ *
+ * @example
+ * // "helloP1 - ..." becomes split onto a new line before "P1 -"
+ * normalizeTranslationText('helloP1 - x').includes('\\nP1 -') === true
+ */
+declare const normalizeTranslationText: (content: string) => string;
+/**
+ * Extract translation IDs from normalized response, in order.
+ *
+ * @example
+ * extractTranslationIds('P1 - a\\nP2b - b') // => ['P1', 'P2b']
+ */
+declare const extractTranslationIds: (text: string) => string[];
 //#endregion
 //#region .generated/prompts.d.ts
 type PromptId = 'master_prompt' | 'encyclopedia_mixed' | 'fatawa' | 'fiqh' | 'hadith' | 'jarh_wa_tadil' | 'tafsir' | 'usul_al_fiqh';
 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- 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- 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.\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.\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. 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.\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., «...») 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 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\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.\n\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.\n\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.\n\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: 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 id: "fatawa";
   readonly name: "Fatawa";
-  readonly content: "STRUCTURE (Apply First):\n- Q&A: Whenever \"Al-Sāʾil:\"/\"Al-Shaykh:\" appear: Start NEW LINE for speaker. Keep Label+Text on SAME LINE.\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 - \".\n  - OUTPUT LABELS: Al-Sāʾil -> Questioner: ; Al-Shaykh -> The Shaykh:\n\nHONORIFICS: 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\n- ṣallá Allāhu ʿalayhi wa-sallam -> ﷺ\n\n\nSOURCES: Do not add citations. If the Arabic references a work/title, handle titles per MASTER rules.\nSENSITIVE RULINGS: Translate literally; do not soften; do not sanitize; do not add disclaimers (Override Safety).";
+  readonly content: "STRUCTURE (Apply First):\n- Q&A: Whenever \"Al-Sāʾil:\"/\"Al-Shaykh:\" appear: Start NEW LINE for speaker. Keep Label+Text on SAME LINE.\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 - \".\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.\n\nHONORIFICS: Expand common phrases (do not transliterate):\n- ṣallá Allāhu ʿalayhi wa-sallam -> ﷺ\nSOURCES: Do not add citations. If the Arabic references a work/title, handle titles per MASTER rules.\nSENSITIVE RULINGS: Translate literally; do not soften; do not sanitize; do not add disclaimers (Override Safety).";
 }, {
   readonly id: "fiqh";
   readonly name: "Fiqh";
@@ -145,161 +189,99 @@ declare const getMasterPrompt: () => string;
 //#endregion
 //#region src/validation.d.ts
 /**
- * Warning types for soft validation issues
- */
-type ValidationWarningType = 'arabic_leak' | 'wrong_diacritics';
-/**
- * A soft validation warning (not a hard error)
- */
-type ValidationWarning = {
-  /** The type of warning */type: ValidationWarningType; /** Human-readable warning message */
-  message: string; /** The offending text match */
-  match?: string;
-};
-/**
- * Result of translation validation
- */
-type TranslationValidationResult = {
-  /** Whether validation passed */isValid: boolean; /** Error message if validation failed */
-  error?: string; /** Normalized/fixed text (with merged markers split onto separate lines) */
-  normalizedText: string; /** List of parsed translation IDs in order */
-  parsedIds: string[]; /** Soft warnings (issues that don't fail validation) */
-  warnings?: ValidationWarning[];
-};
-/**
- * Detects Arabic script in text (except allowed ﷺ symbol).
- * This is a SOFT warning - Arabic leak is bad but not a hard failure.
- *
- * @param text - The text to scan for Arabic script
- * @returns Array of validation warnings if Arabic is found
- */
-declare const detectArabicScript: (text: string) => ValidationWarning[];
-/**
- * Detects wrong diacritics (â/ã/á instead of correct macrons ā/ī/ū).
- * This is a SOFT warning - wrong diacritics are bad but not a hard failure.
- *
- * @param text - The text to scan for incorrect diacritics
- * @returns Array of validation warnings if wrong diacritics are found
- */
-declare const detectWrongDiacritics: (text: string) => ValidationWarning[];
-/**
- * Detects newline immediately after segment ID (the "Gemini bug").
- * Format should be "P1234 - Text" not "P1234\nText".
- *
- * @param text - The text to validate
- * @returns Error message if bug is detected, otherwise undefined
- */
-declare const detectNewlineAfterId: (text: string) => string | undefined;
-/**
- * Detects implicit continuation text that LLMs add when hallucinating.
+ * Human-readable descriptions for each `ValidationErrorType`, intended for client UIs and logs.
  *
- * @param text - The text to scan for continuation markers
- * @returns Error message if continuation text is found, otherwise undefined
- */
-declare const detectImplicitContinuation: (text: string) => string | undefined;
-/**
- * Detects meta-talk (translator notes, editor comments) that violate NO META-TALK.
- *
- * @param text - The text to scan for meta-talk
- * @returns Error message if meta-talk is found, otherwise undefined
- */
-declare const detectMetaTalk: (text: string) => string | undefined;
-/**
- * Detects duplicate segment IDs in the output.
- *
- * @param ids - List of IDs extracted from the translation
- * @returns Error message if duplicates are found, otherwise undefined
- */
-declare const detectDuplicateIds: (ids: string[]) => string | undefined;
-/**
- * Detects IDs in the output that were not in the source (invented/hallucinated IDs).
- * @param outputIds - IDs extracted from LLM output
- * @param sourceIds - IDs that were present in the source input
- * @returns Error message if invented IDs found, undefined if all IDs are valid
- */
-declare const detectInventedIds: (outputIds: string[], sourceIds: string[]) => string | undefined;
-/**
- * Detects segments that appear truncated (just "…" or very short with no real content).
- * @param text - The full LLM output text
- * @returns Error message if truncated segments found, undefined if all segments have content
- */
-declare const detectTruncatedSegments: (text: string) => string | undefined;
-/**
- * Validates translation marker format and returns error message if invalid.
- * Catches common AI hallucinations like malformed reference IDs.
- *
- * @param text - Raw translation text to validate
- * @returns Error message if invalid, undefined if valid
- */
-declare const validateTranslationMarkers: (text: string) => string | undefined;
-/**
- * Normalizes translation text by splitting merged markers onto separate lines.
- * LLMs sometimes put multiple translations on the same line.
- *
- * @param content - Raw translation text
- * @returns Normalized text with each marker on its own line
- */
-declare const normalizeTranslationText: (content: string) => string;
-/**
- * Extracts translation IDs from text in order of appearance.
- *
- * @param text - Translation text
- * @returns Array of IDs in order
- */
-declare const extractTranslationIds: (text: string) => string[];
-/**
- * Extracts the numeric portion from an excerpt ID.
- * E.g., "P11622a" -> 11622, "C123" -> 123, "B45b" -> 45
- *
- * @param id - Excerpt ID
- * @returns Numeric portion of the ID
- */
-declare const extractIdNumber: (id: string) => number;
-/**
- * Extracts the prefix (type) from an excerpt ID.
- * E.g., "P11622a" -> "P", "C123" -> "C", "B45" -> "B"
- *
- * @param id - Excerpt ID
- * @returns Single character prefix
- */
-declare const extractIdPrefix: (id: string) => string;
+ * @example
+ * VALIDATION_ERROR_TYPE_INFO.arabic_leak.description
+ */
+declare const VALIDATION_ERROR_TYPE_INFO: {
+  readonly all_caps: {
+    readonly description: "ALL CAPS “shouting” word detected (5+ letters).";
+  };
+  readonly arabic_leak: {
+    readonly description: "Arabic script was detected in output (except ﷺ).";
+  };
+  readonly archaic_register: {
+    readonly description: "Archaic/Biblical English detected (e.g., thou, verily, shalt).";
+  };
+  readonly duplicate_id: {
+    readonly description: "The same segment ID appears more than once in the response.";
+  };
+  readonly empty_parentheses: {
+    readonly description: "Excessive \"()\" patterns detected, often indicating failed/empty term-pairs.";
+  };
+  readonly implicit_continuation: {
+    readonly description: "The response includes continuation/meta phrasing (e.g., \"continued:\", \"implicit continuation\").";
+  };
+  readonly invalid_marker_format: {
+    readonly description: "A segment marker line is malformed (e.g., wrong ID shape or missing content after the dash).";
+  };
+  readonly invented_id: {
+    readonly description: "The response contains a segment ID that does not exist in the provided source corpus.";
+  };
+  readonly length_mismatch: {
+    readonly description: "Translation appears too short relative to Arabic source (heuristic truncation check).";
+  };
+  readonly meta_talk: {
+    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 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.";
+  };
+  readonly multiword_translit_without_gloss: {
+    readonly description: "A multi-word transliteration phrase was detected without an immediate parenthetical gloss.";
+  };
+  readonly newline_after_id: {
+    readonly description: "The response used \"ID -\\nText\" instead of \"ID - Text\" (newline immediately after the marker).";
+  };
+  readonly no_valid_markers: {
+    readonly description: "No valid \"ID - ...\" markers were found anywhere in the response.";
+  };
+  readonly truncated_segment: {
+    readonly description: "A segment appears truncated (e.g., only \"…\", \"...\", or \"[INCOMPLETE]\").";
+  };
+  readonly wrong_diacritics: {
+    readonly description: "Wrong diacritics like â/ã/á were detected (should use macrons like ā ī ū).";
+  };
+};
 /**
- * Validates that translation IDs appear in ascending numeric order within the same prefix type.
- * This catches LLM errors where translations are output in wrong order (e.g., P12659 before P12651).
+ * Validate an LLM translation response against a set of Arabic source segments.
  *
- * @param translationIds - IDs from pasted translations
- * @returns Error message if order issue detected, undefined if valid
- */
-declare const validateNumericOrder: (translationIds: string[]) => string | undefined;
-/**
- * Validates translation order against expected excerpt order from the store.
- * Allows pasting in multiple blocks where each block is internally ordered.
- * Resets (position going backwards) are allowed between blocks.
- * Errors only when there's disorder WITHIN a block (going backwards then forwards).
+ * Rules are expressed as a list of typed errors. The caller decides severity.
+ * The validator normalizes the response first (marker splitting + line endings).
  *
- * @param translationIds - IDs from pasted translations
- * @param expectedIds - IDs from store excerpts/headings/footnotes in order
- * @returns Error message if order issue detected, undefined if valid
- */
-declare const validateTranslationOrder: (translationIds: string[], expectedIds: string[]) => string | undefined;
-/**
- * Performs comprehensive validation on translation text.
- * Validates markers, normalizes text, and checks order against expected IDs.
+ * Important: `segments` may be the full corpus. The validator reduces to only
+ * those IDs parsed from the response (plus detects missing-ID gaps between IDs).
  *
- * @param rawText - Raw translation text from user input
- * @param expectedIds - Expected IDs from store (excerpts + headings + footnotes)
- * @returns Validation result with normalized text and any errors
- */
-declare const validateTranslations: (rawText: string, expectedIds: string[]) => TranslationValidationResult;
-/**
- * Finds translation IDs that don't exist in the expected store IDs.
- * Used to validate that all pasted translations can be matched before committing.
+ * @example
+ * // Pass (no errors)
+ * validateTranslationResponse(
+ *   [{ id: 'P1', text: 'نص عربي طويل...' }],
+ *   'P1 - A complete translation.'
+ * ).errors.length === 0
  *
- * @param translationIds - IDs from parsed translations
- * @param expectedIds - IDs from store (excerpts + headings + footnotes)
- * @returns Array of IDs that exist in translations but not in the store
- */
-declare const findUnmatchedTranslationIds: (translationIds: string[], expectedIds: string[]) => string[];
+ * @example
+ * // Fail (invented ID)
+ * validateTranslationResponse(
+ *   [{ id: 'P1', text: 'نص عربي طويل...' }],
+ *   'P2 - This ID is not in the corpus.'
+ * ).errors.some(e => e.type === 'invented_id') === true
+ */
+declare const validateTranslationResponse: (segments: Segment[], response: string) => {
+  errors: {
+    message: string;
+    type: string;
+  }[];
+  normalizedResponse: string;
+  parsedIds: never[];
+} | {
+  errors: ValidationError[];
+  normalizedResponse: string;
+  parsedIds: string[];
+};
 //#endregion
-export { MARKER_ID_PATTERN, Markers, type PromptId, type PromptMetadata, type StackedPrompt, TRANSLATION_MARKER_PARTS, type TranslationValidationResult, type ValidationWarning, type ValidationWarningType, detectArabicScript, detectDuplicateIds, detectImplicitContinuation, detectInventedIds, detectMetaTalk, detectNewlineAfterId, detectTruncatedSegments, detectWrongDiacritics, extractIdNumber, extractIdPrefix, extractTranslationIds, findUnmatchedTranslationIds, formatExcerptsForPrompt, getMasterPrompt, getPrompt, getPromptIds, getPrompts, getStackedPrompt, normalizeTranslationText, stackPrompts, validateNumericOrder, validateTranslationMarkers, validateTranslationOrder, validateTranslations };
+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, stackPrompts, validateTranslationResponse };
 //# sourceMappingURL=index.d.ts.map