Document completed phase 5 branch support

docs/critical_tables_db_model.md

@@ -127,6 +127,11 @@ Each branch can carry:
 - branch raw affix text
 - parsed JSON
 
+Current implementation note:
+
+- `critical_branch` is now populated by the importer and returned by the web critical lookup
+- condition keys are normalized for lookup/API use, while the original condition text remains available for display
+
 ### 7. `critical_effect`
 
 Normalized machine-readable effects parsed from the symbol line and, over time, from prose.
@@ -204,82 +209,58 @@ or:
 
 ## Example return object
 
-This is the shape I would return from a lookup:
+This is close to the current lookup shape, while still leaving room for future `critical_effect` normalization:
 
 ```json
 {
   "critical_type": "slash",
   "table_name": "Slash Critical Strike Table",
   "group": null,
-  "column": {
-    "key": "B",
-    "label": "B",
-    "role": "severity"
-  },
-  "roll": {
-    "input": 38,
-    "band": "36-45",
-    "min": 36,
-    "max": 45
-  },
+  "column": "B",
+  "column_label": "B",
+  "column_role": "severity",
+  "roll": 38,
+  "roll_band": "36-45",
+  "roll_band_min": 36,
+  "roll_band_max": 45,
   "description": "Strike foe in shin.",
-  "raw_affix_text": "+2H - must_parry",
-  "affixes": [
+  "raw_affix_text": null,
+  "branches": [
     {
-      "effect_code": "direct_hits",
-      "value": 2
-    }
-  ],
-  "conditions": [
-    {
-      "when": "with leg greaves",
-      "description": null,
+      "branch_kind": "conditional",
+      "condition_key": "with_leg_greaves",
+      "condition_text": "with leg greaves",
+      "description": "",
       "raw_affix_text": "+2H - must_parry",
-      "affixes": [
-        {
-          "effect_code": "direct_hits",
-          "value": 2
-        },
-        {
-          "effect_code": "must_parry_rounds",
-          "value": 1
-        }
-      ]
+      "sort_order": 1
     },
     {
-      "when": "without leg greaves",
+      "branch_kind": "conditional",
+      "condition_key": "without_leg_greaves",
+      "condition_text": "w/o leg greaves",
       "description": "You slash open foe's shin.",
       "raw_affix_text": "+2H - bleed",
-      "affixes": [
-        {
-          "effect_code": "direct_hits",
-          "value": 2
-        },
-        {
-          "effect_code": "bleed_per_round",
-          "value": 1
-        }
-      ]
+      "sort_order": 2
     }
   ],
-  "raw_text": "Original full cell text as extracted from the PDF",
+  "raw_cell_text": "Original full cell text as extracted from the PDF",
   "source": {
     "pdf": "Slash.pdf",
-    "page": 1,
-    "extraction_method": "text"
+    "extraction_method": "xml"
   }
 }
 ```
 
 ## Ingestion notes
 
-Recommended import flow:
+Current import flow:
 
 1. Create `critical_table`, `critical_group`, `critical_column`, and `critical_roll_band` from each PDF's visible axes.
-2. Store each cell in `critical_result.raw_cell_text` exactly as extracted.
-3. Parse the symbol line into `critical_effect`.
-4. Split explicit conditional branches into `critical_branch`.
-5. Gradually enrich prose-derived effects such as death, blindness, paralysis, limb loss, initiative changes, and item breakage.
-6. Route image PDFs like `Void.pdf` through OCR before the same parser.
+2. Store each base cell in `critical_result` with base raw/description/affix text.
+3. Split explicit conditional branches into `critical_branch`.
+4. Return the base result plus ordered branches through the web critical lookup.
+5. Parse symbolic affixes into `critical_effect` in the next phase.
+6. Gradually enrich prose-derived effects such as death, blindness, paralysis, limb loss, initiative changes, and item breakage.
+7. Route image PDFs like `Void.pdf` through OCR before the same parser.
 
 The important design decision is: never throw away the original text. The prose is too irregular to rely on normalized fields alone.