Fix every real lint finding and drop degenerate splice fragments

docs/adr/0004-chunking-strategy.md

@@ -0,0 +1,130 @@
+# ADR 0004: Chunking strategy for drug monographs — validated against real per-section measurements
+
+## Status
+
+Accepted for the monograph range (printed pp. 99-1496) only. General
+chapters (pp. 37-98) and appendices (pp. 1497-1528) are explicitly out of
+scope — see Consequences.
+
+## Context
+
+`docs/architecture.md`'s original "Chunking" paragraph specified `(drug,
+section)` as the chunk unit, a ~500-800 token budget, and a 400-token/
+50-overlap sliding window for oversized sections. Those numbers were written
+before segmentation existed — a plausible guess, never checked against real
+per-section text length.
+
+Phase 1 (extract → segment → validate) is now real, tested code producing
+682 real monographs from the full 1668-page source PDF. This session ran
+`python -m ingestion.cli run` for real and measured actual per-section
+length across the whole corpus with a temporary investigation script
+(`ingestion/scratch/chunking_stats_survey.py`, deleted after this ADR
+captured its findings, per this project's investigation-script rule) —
+something that had never been measured before this ADR.
+
+## What was actually measured (whole corpus, 682 monographs)
+
+- Sections per monograph: min 11, median 17, max 19 (of ~18-19 known
+  section keys in `segment/vocab.py`'s open taxonomy).
+- Whole-monograph length: median 11,480 chars, p90 19,068 chars, max 38,786
+  chars.
+- Per-section length, converted to a **chars/4 token estimate — an
+  estimate, not a real tokenizer count**:
+  - Most of the ~18 section types sit comfortably under 800 estimated
+    tokens even at their p90 (e.g. `chi_dinh` p90≈268 tok, `dang_thuoc_va_
+    ham_luong` p90≈115 tok, `tac_dung_khong_mong_muon` p90≈481 tok).
+  - **Two sections routinely exceed 800 tokens**:
+    `duoc_ly_va_co_che_tac_dung` (242 of 678 monographs that have this
+    section, 35.7%, max ≈3542 tok) and `lieu_luong_va_cach_dung` (200 of
+    675, 29.6%, max ≈3631 tok).
+  - A smaller tail also exceeds it: `than_trong` (25/680, 3.7%),
+    `tuong_tac_thuoc` (22/642, 3.4%).
+  - This means: the original 800-token ceiling is directionally correct
+    (it clears ~16 of 18 section types at their p90 with room to spare),
+    but "sub-chunk in that case" is not a rare hedge as originally implied
+    — it is the routine path for roughly a third of all monographs, on two
+    specific, named, high-clinical-importance sections (mechanism of
+    action and dosing).
+
+**A separate, blocking bug was found while gathering this data, not fixed
+by this ADR** (out of scope — belongs to `extract`/`segment`, owned by a
+parallel session at the time of writing): running header/footer
+boilerplate ("DTQGVN 2" + page number + repeated drug name, tagged
+`column="full_width"` in `extract/spans.py`) is never filtered out of
+section body text before it reaches `SectionSpan.text`. Measured:
+1,374 of 11,409 sections (12.0%) contain a literal "DTQGVN" string
+mid-text; 671 of 682 monographs (98.4%) have at least one affected section
+(e.g. MORPHIN SULFAT's `lieu_luong_va_cach_dung`: `"...Nếu\nDTQGVN 2\n1009\n
+Morphin sulfat\nuống viên thuốc..."`). This is `docs/pdf-parsing-outlier-
+catalog.md` item 13's known risk, measured whole-corpus for the first time
+here. **Chunking must not run against real data until this is fixed** —
+otherwise boilerplate is baked into embeddings and can surface mid-sentence
+in a chunk shown to a doctor or pharmacist.
+
+## Decision
+
+1. **Chunk unit stays `(drug_id, section_key)`** — matches
+   `segment/models.py`'s existing `Monograph.sections: Dict[str,
+   SectionSpan]`, matches how a doctor/pharmacist would query ("what does
+   it say about liều dùng"), and lets a citation point at one clinical
+   section rather than a whole 2,000-19,000-char monograph.
+2. **Token budget: keep the 800-token ceiling** (chars/4 estimate) as the
+   split trigger. Below it, a section is one chunk, verbatim. This is now a
+   validated choice, not a guess.
+3. **Sub-chunking only applies to the long-tail sections above** (~30-36%
+   of monographs for the two named sections, a few percent for the rest).
+   Method: **sentence-boundary-aware sliding window**, replacing the
+   originally-guessed fixed-character window. Target ~600-700 tokens per
+   sub-chunk (headroom under the 800 ceiling), ~1 sentence / 50-80 token
+   overlap between adjacent sub-chunks. Split only at a sentence boundary
+   (`.`/`;`/`:` followed by whitespace + capital letter), explicitly not
+   treating a Vietnamese decimal comma (e.g. "0,425") as a boundary.
+4. **Why sentence-aware, not line- or character-based**: `assembler.py`
+   joins `body_lines` one line per PyMuPDF *span*, i.e. one PDF visual
+   line-wrap point — not a semantic paragraph or sentence boundary. A blind
+   character/line window can split a sentence mid-way. This is a real,
+   measured risk here, not theoretical: outlier-catalog item 17 found
+   adult/child dosing splits ("Người lớn"/"Trẻ em") appear on 1,121 of
+   ~1,400 monograph-range pages — a chunk boundary landing inside one of
+   those sentences would be a patient-safety-relevant defect, not a
+   cosmetic one.
+5. **Chunk metadata / provenance** (extends the existing `drug_name,
+   section_type, source_page_range, chunk_id` list in `docs/architecture.md`
+   — per CLAUDE.md's provenance rule): `chunk_id`
+   (`{drug_id}__{section_key}__{part_index}`), `drug_id`, `drug_name`,
+   `section_key`, `section_display_name`, `atc_codes` (inherited from the
+   monograph — enables ATC-class-filtered retrieval), `source_page_range`
+   (monograph-level, see Consequences), `part_index`/`part_count` (`0`/`1`
+   for un-split sections, keeps the schema uniform across all chunks).
+
+## Consequences
+
+- **Scope**: this decision covers the monograph range only. General
+  chapters and appendices contain real tables and 2D stacked-fraction
+  formulas (`docs/document-profile.md`, investigation in progress as of
+  this ADR) that need their own structural survey before any chunking rule
+  can be designed for them — do not extend this ADR's rules to those ranges
+  without a fresh investigation.
+- **Hard prerequisite**: the boilerplate-leakage bug described above must
+  be fixed in `extract`/`segment` before this chunking design is run
+  against real data for ingestion. This ADR does not fix it.
+- **Known gap — sub-compound tagging inside class-level monographs**: 25.5%
+  of the corpus has more than one ATC code per monograph (outlier item
+  12a), e.g. "VITAMIN D VÀ CÁC THUỐC TƯƠNG TỰ" documents dosing for 7
+  different analogues inside one `lieu_luong_va_cach_dung` section. No
+  reliable structural signal was found in sampled text to split a section
+  by sub-compound — a chunk from this section is tagged with the class
+  name only, not the specific analogue a query might target. Deferred to
+  golden-dataset-driven eval rather than guessed at now.
+- **Known gap — sub-chunk page precision**: `source_page_range` is
+  monograph-level, not sub-chunk-exact. A sub-chunk from late in a
+  multi-page section inherits the whole monograph's page range rather than
+  its own precise page, because per-line page tracking doesn't currently
+  exist in `SectionSpan`/`Heading`. The monograph + section-heading page is
+  still real, checkable provenance, but this is a known precision gap, not
+  full sub-chunk traceability. Flagged as a future improvement.
+- **Not yet built**: the Vietnamese sentence-boundary splitter itself
+  (abbreviation handling, decimal-comma handling, ATC-code-period handling)
+  is specified here as a rule, not implemented or unit-tested. Building and
+  testing it is a separate, later task (`ingestion/ingestion/chunk/`, which
+  does not exist yet).

docs/adr/0005-segment-output-contract-for-chunking.md

@@ -0,0 +1,216 @@
+# ADR 0005: `segment/` output contract needed by `chunk/` — structure-preserving, not flattened
+
+## Status
+
+Proposed. **Contract/schema only — no implementation.** `segment/models.py`,
+`segment/assembler.py`, and `segment/io.py` are actively owned by a parallel
+session on the same checkout at the time of writing; this ADR specifies what
+`chunk/` needs from `segment/`'s output precisely enough to implement and
+test, but does not touch those files itself. Supersedes part of ADR 0004
+(see "Relationship to ADR 0004" below) — ADR 0004's `(drug_id, section_key)`
+chunk-unit-as-leaf assumption is corrected here to `(drug_id, section_key)`
+as a **parent**, with sentence-window splitting demoted from primary
+strategy to fallback.
+
+## Context
+
+ADR 0004 designed chunking against `segment/models.py`'s current output:
+`SectionSpan.text` is a single flattened string per section (`"\n".join(
+body_line.strip() for ...)`), with all per-line style (`Span.bold`) and
+per-line page position discarded once the string is built (confirmed by
+reading `assembler.py`: `body_lines.append(span.text.strip())` keeps only
+`span.text`, nothing else). Review of ADR 0004 surfaced four real problems
+that trace back to this flattening, not to the chunking algorithm itself:
+
+1. **A section is not a single semantic unit.** `liều lượng và cách dùng`
+   and `tương tác thuốc` routinely contain multiple distinct facts (dosing
+   per patient population, dosing per organ-function impairment, multiple
+   separate drug interactions) that a doctor may want to retrieve
+   independently. Measured: an explicit population marker ("Người lớn"/
+   "Trẻ em"/"Trẻ sơ sinh"/"Suy thận"/"Suy gan" immediately followed by `:`
+   or `.`) appears in **303 of 675 monographs (44.9%)** that have a `liều
+   lượng và cách dùng` section — this is common, not an edge case.
+2. **A blind sentence-boundary sliding window (ADR 0004's original
+   sub-chunking method) can still split two different facts into the same
+   chunk, or split one fact across two chunks**, because it has no way to
+   know a population/interaction boundary exists — that information exists
+   in the source (as a bold or otherwise visually distinct sub-heading, per
+   direct reading of MORPHIN SULFAT/VITAMIN D section text: lines like
+   "Thuốc uống", "Cách dùng:" render as isolated bold short lines in the
+   PDF) but is discarded before `chunk/` ever sees it.
+3. **Tables inside the monograph range are not addressed at all.** ADR 0004
+   implicitly assumed monograph-range sections are prose. `docs/pdf-parsing-
+   outlier-catalog.md` item 19 already documents a real table (dosing by
+   renal function, HSV/CMV columns) inside a monograph body (Foscarnet
+   natri, physical page 698) — flattening a table's rows into
+   newline-joined body text destroys its row/column structure exactly the
+   way outlier item 7 already describes for the appendix's 2D nomogram
+   table. A whole-range survey to size this properly is in progress
+   alongside this ADR (see "Not yet resolved" below).
+4. **Provenance is section-level, not chunk-level**, because per-line
+   `physical_page`/`y0` (which `Span` already carries — see
+   `extract/models.py`) is discarded at the same flattening point. For a
+   section spanning several physical pages, a sub-chunk built from its
+   final third currently has no way to know its own real page — it can
+   only inherit the whole monograph's `source_page_range`. For medical
+   citations this is not precise enough.
+
+**A fifth, independently-found data-quality bug makes precise provenance
+even more necessary, not less**: the corpus's last-processed monograph
+(ZOLPIDEM) is never closed until true end-of-stream, and `assembler._classify`
+calls `match_section()`/`match_section_with_inline_value()` on every span
+with **no `in_monograph_range` gate** (unlike `_TextEvent` handling, which
+does check it). A spurious bold-text match on physical page 1655 — deep in
+the back-of-book "Mục lục tra cứu" brand-name index, confirmed by reading
+that page directly — overwrote ZOLPIDEM's real `tương tác thuốc`
+`SectionSpan` with an empty one and corrupted its `source_page_range` to
+`[1492, 1655]`. This is real content loss (measured: exactly 1 monograph
+affected, the last one processed — every other monograph is closed on
+schedule by the next monograph title, which *is* range-gated). Flagged for
+the session that owns `extract`/`segment`, not fixed here.
+
+## Decision
+
+Extend `segment/models.py`'s `SectionSpan` with a structured, line-level
+representation, additive to (not replacing) the existing flat `text` field
+— `chunk/` becomes a real, structure-aware consumer instead of re-deriving
+structure from a flattened string via ad hoc regex.
+
+### New/changed types (`segment/models.py`)
+
+```python
+@dataclass(frozen=True)
+class BodyLine:
+    text: str
+    physical_page: int
+    y0: float
+    bold: bool          # Span.bold, preserved instead of discarded
+
+@dataclass
+class SectionSpan:
+    key: str
+    display_name: str
+    heading: Heading
+    text: str                              # UNCHANGED meaning, kept for
+                                            # backward compat (see invariant below)
+    lines: List[BodyLine] = field(default_factory=list)   # NEW
+```
+
+`lines` carries exactly the per-line signal `chunk/` needs to do its own
+job (population/subheading detection, precise page provenance) without
+`segment/` having to know anything about chunking — `segment/`'s
+responsibility stays "detect boundaries and preserve source structure," not
+"decide what a retrieval unit is" (Clean Architecture / SoC, per
+CLAUDE.md). Specifically, this is deliberately **not** a `is_subheading:
+bool` field computed by `segment/` — classifying "is this line a
+subheading a chunker should split on" is a chunking-time decision (what
+counts as a good split point can vary by strategy/eval results), not a
+segmentation-time one. `segment/` should stop discarding the raw signal
+(`bold`, `y0`, `physical_page`) it already has per span; it should not also
+start doing chunk-shaping judgment calls.
+
+### Invariants
+
+1. `text == "\n".join(l.text for l in lines).strip()` for every
+   `SectionSpan`, for the lifetime of this contract — `lines` is a strictly
+   additive refinement, never a divergent second source of truth. Any
+   change to how body text is assembled (e.g. the boilerplate-stripping fix
+   already applied by the other session) must update both fields from the
+   same filtered span list, not `text` alone.
+2. `lines` is in reading order, matching the order `text`'s lines already
+   implicitly have.
+3. Every `BodyLine.physical_page` satisfies `detector.in_monograph_range`
+   for a `Span` on that page — i.e., **no line in any `SectionSpan.lines`
+   may come from outside the monograph's real printed-page range**. This is
+   the ZOLPIDEM bug's exact failure mode stated as an invariant: it was
+   violated (a spurious section event was accepted from a fully
+   out-of-range page precisely because no such check existed for section
+   *events*, only for body *text* events). Enforcing this invariant closes
+   that bug as a side effect, but the invariant is stated here as a
+   contract requirement independent of any specific fix implementation.
+4. Every currently-open monograph must be finalized exactly once, at either
+   (a) the next monograph title, or (b) true end-of-stream — with no third
+   path (e.g., a stray out-of-range section match) able to silently mutate
+   an already-"complete" monograph's sections after point (a) would
+   otherwise have applied. (This is a restatement of invariant 3 from the
+   monograph-lifecycle side, not a new requirement.)
+
+### Migration impact
+
+- **`segment/io.py`** (`_monograph_to_dict`/`_monograph_from_dict`,
+  `write_monographs_jsonl`/`read_monographs_jsonl`): additive — serialize
+  `lines` alongside the existing `text`/`heading` fields per section.
+  Existing consumers reading only `text` (e.g. `segment/atc.py`'s
+  `extract_atc_codes`, which regexes over `SectionSpan.text`) need no
+  change, per invariant 1.
+- **`ingestion/data/processed/monographs.jsonl`**: schema grows a new
+  optional-shaped field (`sections[key].lines`). No `schema_version` field
+  currently exists in the serialized dict (checked `io.py` directly) —
+  worth adding as part of this change, both for this migration and because
+  `docs/architecture.md` already assumes "collection aliasing allows
+  re-ingesting with a changed chunking strategy," which implies the
+  ingestion output itself should be able to declare which schema shape it
+  is.
+- **Existing 110 tests**: unaffected if invariant 1 holds — no assertion in
+  the current suite inspects `lines` (it doesn't exist yet), and `text`'s
+  value/semantics are unchanged.
+- **New tests required** (this ADR specifies them; implementation and the
+  actual test code are not part of this ADR):
+  1. Regression test reproducing the ZOLPIDEM failure shape: a synthetic
+     span stream — last monograph's title and real sections, followed by
+     spans whose `printed_page` is out of `in_monograph_range` but whose
+     text matches a `vocab.py` section label — asserting the monograph
+     closes with its real sections intact and the out-of-range spurious
+     match is ignored, not accepted.
+  2. `SectionSpan.lines` fixture test: using the real MORPHIN SULFAT
+     boilerplate-fix fixture already in `tests/test_segment_assembler.py`,
+     assert `lines` preserves the correct `bold`/`physical_page`/`y0` per
+     retained line (and that stripped boilerplate lines are absent from
+     `lines` too, not just from `text`).
+  3. Round-trip test: `write_monographs_jsonl` → `read_monographs_jsonl`
+     preserves `lines` exactly (dataclass equality per line).
+  4. Whole-corpus invariant-1 check: for a real `cli run` output, assert
+     `text == "\n".join(l.text for l in lines).strip()` holds for every
+     section of every monograph, not a sample.
+
+## Relationship to ADR 0004
+
+ADR 0004's chunk-unit decision (`(drug_id, section_key)`) is **not**
+discarded — a section is still the natural *parent* grouping (matches how a
+clinician thinks, matches `Monograph.sections`). What changes: ADR 0004
+described a section as directly *the* chunk when under the 800-token
+ceiling, with sentence-window splitting as the fallback for oversized
+sections. Per the review above, splitting must instead **first** attempt to
+break at real structural boundaries available in `SectionSpan.lines` (a
+bold, short, isolated line — the same "subheading" shape already visually
+confirmed for route-of-administration/population sub-headers — or an
+explicit population/organ-function marker), with the sentence-window method
+demoted to a fallback for the remaining prose that has no such marker. The
+exact splitting algorithm (how a "subheading-shaped line" is defined
+precisely, in code) is a `chunk/`-side implementation detail *enabled* by
+this contract, not decided by it.
+
+## Not yet resolved (explicitly out of scope for this ADR)
+
+- **Table/formula content blocks.** A separate whole-monograph-range survey
+  (pdfplumber `find_tables()` + PyMuPDF math-symbol scan, physical pages
+  98-1494 excluding blank page 99 — the exact set `detector.
+  in_monograph_range` accepts, not an assumed offset) is in progress at the
+  time of writing, per explicit user instruction to measure before deciding
+  a table/formula chunk-unit strategy. This ADR's `BodyLine`
+  contract covers **text content only**; a table/formula region should
+  *not* currently be flattened into `BodyLine`s (doing so would repeat
+  exactly the "destroys row/column meaning" mistake outlier item 7 already
+  documents) — but the precise `ContentBlock`/table-row/formula-unit shape
+  is deferred to a follow-up revision of this ADR once the survey reports
+  real numbers (how many monographs/sections affected, page-break
+  continuation frequency, multi-tier headers, merged cells, footnotes).
+- **Paragraph-boundary detection** (grouping consecutive `BodyLine`s into a
+  flowing paragraph vs. a new one) is left to `chunk/`, using the same
+  kind of y-gap heuristic `segment/merge.py` already validates for
+  multi-line title wraps (`_MAX_LINE_GAP_PT`) — `BodyLine.y0` is sufficient
+  raw signal for `chunk/` to compute this itself; `segment/` does not need
+  to pre-compute paragraph grouping.
+- **The actual `chunk/` splitting implementation** (subheading detector,
+  population-marker regex, sentence-window fallback) is not part of this
+  ADR — this ADR defines the data contract that implementation will consume.

docs/adr/0006-quarantined-block-references-in-chunks.md

@@ -0,0 +1,171 @@
+# ADR 0006: chunks must carry references to lifted table/formula blocks
+
+## Status
+
+Proposed, with implementation to follow immediately. Resolves the item ADR
+0005 explicitly deferred ("Table/formula content blocks … the precise
+`ContentBlock`/table-row/formula-unit shape is deferred to a follow-up
+revision of this ADR once the survey reports real numbers"). The survey has
+reported.
+
+## Context
+
+`segment/` now lifts table and formula regions out of section prose and
+quarantines them (ADR 0003 lineage, outlier-catalog items 7, 8, 24, 25).
+That was the right move — linearised, AMPICILIN VÀ SULBACTAM's
+Cockcroft-Gault fraction read as `Clcr (ml/phút) = 72 x creatinin huyết
+thanh`, i.e. a division presented as a multiplication, in a renal-dosing
+section.
+
+But `chunk/models.py` has no field that refers to a lifted block. Measured on
+the current whole-corpus output:
+
+| quantity | value |
+|---|---|
+| lifted blocks | 167, all quarantined |
+| monographs affected | 96 of 683 (**14.1%**) |
+| sections affected | 108 |
+| **blocks in `lieu_luong_va_cach_dung`** | **127 (76%)** |
+| next largest section | `duoc_ly_va_co_che_tac_dung`, 16 |
+| shapes | simple_table 136, multi_level_or_merged_header 16, formula_2d 14, cross_page_continuation 1 |
+
+So three quarters of everything removed from prose was removed from the
+dosing section, in a drug formulary, for an audience of doctors and
+pharmacists.
+
+**The failure this creates is silent, not visible.** A chunk of AMPICILIN VÀ
+SULBACTAM's `lieu_luong_va_cach_dung` is grammatical, complete-looking prose
+with the renal-dosing table absent and nothing marking the absence. Retrieval
+ranks it, the model answers from it, and neither has any way to know a table
+was taken out. A visible error would be safer than this.
+
+A second, quieter failure: a table is currently **unreachable**. Nothing in
+the index represents it, so "bảng liều theo chức năng thận của ampicilin"
+cannot retrieve it even in principle.
+
+## Decision
+
+Chunks reference blocks; blocks' content never becomes embedded text.
+
+### 1. `Chunk` gains typed attachments
+
+```python
+@dataclass(frozen=True)
+class ChunkAttachment:
+    block_id: str
+    kind: str            # "table" | "formula"
+    shape: str           # simple_table | multi_level_or_merged_header |
+                         # cross_page_continuation | formula_2d
+    physical_page: int
+    bbox: List[float]
+    quarantined: bool
+    header_row: List[str] = ()   # simple_table only; see caveat below
+
+@dataclass(frozen=True)
+class Chunk:
+    ...
+    chunk_kind: str = "prose"            # "prose" | "block_descriptor"
+    attachments: List[ChunkAttachment] = ()
+    has_quarantined_content: bool = False
+```
+
+`has_quarantined_content` is derivable from `attachments`, and is serialized
+anyway. A consumer that never looks at `attachments` must still be unable to
+miss the fact — the whole defect being fixed here is a consumer not knowing
+what it was not told.
+
+### 2. One descriptor chunk per block, built from metadata only
+
+A block also gets its own chunk so it is retrievable at all:
+
+```
+chunk_id  = "{drug_id}:{section_key}:block:{block_id}"
+chunk_kind = "block_descriptor"
+text       = "AMPICILIN VÀ SULBACTAM — Liều lượng và cách dùng — bảng,
+              trang in 204. Cột: Độ thanh thải creatinin | Nửa đời |
+              Liều ampicilin/sulbactam."
+```
+
+The text is assembled from the drug name, the section display name, the kind,
+the printed page and — for `simple_table` only — the header row. **No cell
+value ever appears.** A header row is a row of labels; linearising it cannot
+invent a numeric relationship, which is precisely what linearising a body row
+does. For every other shape the header is omitted, because
+`multi_level_or_merged_header` is the shape whose header extraction is least
+trustworthy.
+
+Caveat recorded in the schema itself: `header_row` comes from
+`pdfplumber.find_tables()`'s first row and has **not** been verified by eye
+(the 180 real tables' individual shapes are rule-derived; only the 20
+"not a table" verdicts were visually confirmed). It is retrieval bait, never
+an answer.
+
+### 3. The answer layer's obligations (binding on `ai-service`)
+
+These are stated here because they are the reason the schema exists; they are
+not implemented by `ingestion/`.
+
+1. A retrieved chunk with `has_quarantined_content: true` **must** cause the
+   answer to state that a table or formula exists at the cited page, and to
+   surface its rendered crop. The answer may not present itself as complete.
+2. A `block_descriptor` chunk may be answered **only** with the crop. It must
+   never be paraphrased, and its `header_row` must never be presented as the
+   table's content.
+3. No chunk carrying a quarantined attachment may be used to state a numeric
+   dose. If the dose is in the table, the answer is the crop plus the page.
+
+### 4. `schema_version`
+
+`monographs.jsonl` and the chunk output both gain `schema_version`. ADR 0005
+flagged its absence; a schema that now has two chunk kinds and an attachment
+list cannot be safely consumed without one.
+
+## Alternatives rejected
+
+- **Flatten the block into the chunk text.** This is the defect, not the fix
+  — it reproduces `Clcr = 72 x creatinin` exactly.
+- **Chunk the block's linearised text as an ordinary chunk.** Worse than
+  flattening: it makes unsafe text independently retrievable *as prose*, with
+  its quarantine flag one dereference away from being ignored.
+- **Drop the blocks.** Silent loss, and contrary to the standing rule that
+  unreconstructable content is quarantined with full provenance, never
+  deleted.
+- **Rely on the prose saying "xem bảng".** The prose often does not, and a
+  retrieval layer cannot act on an unstructured hint.
+- **Wait for row/column reconstruction and do this once.** Reconstruction is
+  days of work and would leave the corpus unchunkable meanwhile; worse, it
+  would make the schema question look answered when the *silent-incompleteness*
+  problem is independent of whether the rows are recovered. Reconstruction
+  later populates `rows` on the same attachment without touching consumers.
+
+## Why a crop is a legitimate answer, not a placeholder
+
+For doctors and pharmacists a rendered crop of the source page is the
+highest-fidelity response available: it *is* the book, and it is verifiable at
+a glance. Reconstruction earns its keep for a different job — comparing or
+combining values across drugs, which is the synthesis use case this product
+exists for — not for single-table lookup.
+
+## Invariants and gates
+
+Added to `cli chunk-ready` and to the chunk stage's own tests:
+
+1. `section_with_lifted_block_but_no_chunk_reference = 0`
+2. `attachment_block_id_unknown = 0` — every referenced id exists on the
+   monograph
+3. `attachment_without_page_or_bbox = 0`
+4. `block_text_leaked_into_chunk_text = 0` — no chunk's embedded text
+   contains a quarantined block's text
+5. `descriptor_chunk_count == block_count`
+6. `descriptor_chunk_without_attachment = 0`
+
+## Consequences
+
+- Prose chunks shrink slightly in trustworthiness terms but grow in honesty:
+  the ones missing a table now say so.
+- The index gains 167 descriptor chunks (≈1.4% of the expected chunk count),
+  each cheap and none carrying unsafe text.
+- `ai-service` cannot be built to answer a dosing question from prose alone
+  for the 108 affected sections without violating a stated contract.
+- The 14 `formula_2d` attachments make the two Cockcroft-Gault formulas
+  answerable as crops today, which they are not now.