|
| 1 | +<!-- Generated by Cortex wiki_reindex from wiki/adr/cortex/1071-one-reading-of-a-draft-section-for-every-consumer.md; ADR-1071. Read-only mirror: edit the canonical wiki page. --> |
| 2 | + |
| 3 | +--- |
| 4 | +created: 2026-09-16T07:39:09Z |
| 5 | +kind: adr |
| 6 | +number: 1071 |
| 7 | +status: accepted |
| 8 | +tags: [wiki, curation, compile, shared, issue-589] |
| 9 | +title: One reading of a draft section for every consumer |
| 10 | +--- |
| 11 | +# ADR-1071: One reading of a draft section for every consumer |
| 12 | + |
| 13 | +## Status |
| 14 | + |
| 15 | +accepted |
| 16 | + |
| 17 | +## Context |
| 18 | + |
| 19 | +A wiki draft's sections are read in four places, and each spelled out the shape for itself, with different answers (issue #589): |
| 20 | + |
| 21 | +- `core/draft_compiler.py` skipped a section whose heading was falsy, so the published Markdown never carried an untitled section. |
| 22 | +- `handlers/wiki_compile.py` built the `wiki.pages` mirror as a `{heading: body}` comprehension with no guard, so the same section landed in the row under an empty key. The file and its mirror disagreed about the same page. The review of PR #588 demonstrated it: a draft holding `sections=[{"heading": "", "body": "orphan prose"}]` compiled to a `.md` without the section and to `wiki.pages.sections == {"": "orphan prose"}`. |
| 23 | +- `core/draft_curator.py::_missing_required_sections` called `.strip()` on whatever the section held, so a heading that was not text raised `AttributeError` inside `evaluate_draft`, and `getattr(s, "heading", None) or s.get("heading", "")` raised on a `Section` object whose heading was empty. |
| 24 | +- `handlers/wiki_refine.py` had its own `_is_text` since ADR-1070, which is the only one of the four that was right. |
| 25 | + |
| 26 | +A section arrives either as a dict, from an MCP client through `wiki_refine_draft`, or as a `Section` object from the template synthesizer, and ADR-1070 only closed the client entry point. A draft written before it, or by `wiki_synthesize`, still reaches the other three. |
| 27 | + |
| 28 | +Two sections submitted with the same heading were also silently deduped by the mirror's mapping: the second body replaced the first with no error. |
| 29 | + |
| 30 | +## Decision |
| 31 | + |
| 32 | +`mcp_server/shared/wiki_sections.py` states the shape once: `is_text` for a non-blank string, `heading_of` returning the stripped heading or None, `body_of` returning the body or an empty string, and `titled_sections` returning the ordered `(heading, body)` pairs a page can carry. Being in `shared/`, it is reachable from core, handlers and infrastructure alike. |
| 33 | + |
| 34 | +The Markdown renderer, the `wiki.pages` mirror and the curator's required-section lookup all read a draft through `titled_sections`, so the file, the row and the curation verdict describe the same page. `wiki_refine_draft` keeps refusing a malformed section at the entry point, and now also refuses two sections that carry the same heading, since the mirror cannot hold both. |
| 35 | + |
| 36 | +## Consequences |
| 37 | + |
| 38 | +Easier: a page row can no longer carry prose under an empty key, and the curator reports a malformed section as a missing required one instead of raising. |
| 39 | + |
| 40 | +`tests_py/shared/test_wiki_sections.py` covers the four functions over dicts, `Section` objects, missing fields and non-text values. `tests_py/handlers/test_wiki_compile_sections_mirror.py` compiles a draft holding a blank heading, a missing heading and a numeric heading, and asserts the mirror holds only the titled section while the published Markdown omits the orphan prose. `tests_py/core/test_draft_curator_sections.py` drives four malformed shapes through `evaluate_draft`. `test_duplicate_headings_are_refused` covers the refine entry point. Three of those fail on the previous code, one of them with the `AttributeError`. |
| 41 | + |
| 42 | +Harder: a consumer that wanted the raw sections, with their unusable entries, has to read the draft column itself. None does. |
| 43 | + |
| 44 | +Unchanged: what the synthesizer writes, and what `wiki_curate` decides for a well-formed draft. |
0 commit comments