C.E.L_Slide_test2/docs/reference/architecture/5_MDX_STRUCTURE_INVENTORY.md

Five-MDX Structure Inventory

Issue: #98

Purpose: establish the empirical ground truth for T22-T30 before changing the parser, matcher, layout planner, slot mapper, frontend override path, or AI adaptation path.

This inventory intentionally compares three layers:

Column	Meaning	Gap type exposed
A. Original MDX contains	What the source file actually expresses	Source structure
B. Current pipeline sees	What the current task21d_* runs expose in Step 02 / Step 06 / Step 20	Parser, normalizer, component, and planner behavior
C. Expected result	What the slide pipeline should preserve and render	Layout, matching, slot mapping, override, and adaptation behavior

Source files inspected:

• samples/mdx/01. ... .mdx
• samples/mdx/02. ... .mdx
• samples/mdx/03. ... .mdx
• samples/mdx/04. ... .mdx
• samples/mdx/05. ... .mdx

Observed pipeline runs:

• data/runs/task21d_01
• data/runs/task21d_02
• data/runs/task21d_03
• data/runs/task21d_04
• data/runs/task21d_05

MDX 01

A. Original MDX contains	B. Current pipeline sees	C. Expected result	Gap owner
A pre-intro block before the first numbered ## heading. It includes a details/popup block and is user-visible content.	Step 02 only emits 01-1 and 01-2. The pre-intro has no unit id. Existing data/user_overrides/01.json references 01-3, but that id is orphaned.	Promote the pre-intro into a first-class unit such as 01-intro, or define a documented alias/migration path for the existing 01-3 override.	T22 parser/normalizer and override migration
## 1 and ## 2 numbered sections.	Step 06 selects two units: 01-1 -> construction_bim_three_usage, 01-2 -> bim_dx_comparison_table.	Body zones should be based on the normalized section tree after the pre-intro policy is decided.	T24 layout policy
An image reference in section 2 and details/popup content.	Recent asset handling removes broken image icons, but popup/details semantics remain only partially represented.	Image and popup/details nodes must be explicit node types, not raw markdown leftovers.	T22 node taxonomy and T25 slot mapping

MDX 02

A. Original MDX contains	B. Current pipeline sees	C. Expected result	Gap owner
## 1 with goal content and one image.	Step 02 emits 02-1. Step 06 selects construction_goals_three_circle_intersection. A user override exists for 02-1, but frontend/runtime override behavior is not proven end-to-end.	Section 02-1 must remain independently addressable, and selected/overridden frames must render without stale preview or silent fallback.	T28 frontend override E2E
## 2, with ### 2.1 and ### 2.2.	Step 02 emits only parent 02-2; child headings are raw content inside the section.	2.1 and 2.2 should become frame-internal groups under the 02-2 unit, not separate slide zones unless a layout policy explicitly asks for that.	T22/T25
<DxEffect />, which represents the stakeholder/persona effect table in samples/src/components/dx.astro.	The pipeline sees an opaque component tag; persona columns are not expanded into semantic nodes.	Register DxEffect in a component expansion registry and expand it into persona/table nodes before matching and slot mapping.	T23 component expansion

MDX 03

A. Original MDX contains	B. Current pipeline sees	C. Expected result	Gap owner
## 1 with three conceptual groups: technology, people, and environment/nature.	Step 06 selects three_parallel_requirements for 03-1. Technical text coverage is currently PASS.	Child groups should populate the internal pillar labels and body slots of the selected frame. They must not become external slide titles.	T25 slot mapping
## 2 with ### 2.1 process and ### 2.2 product, including table-like content.	Step 06 selects process_product_two_way for 03-2.	Process/product child groups should map to the selected two-way frame with all source atoms preserved.	T25/T27
Dense content in two zones.	Presentation can still become visually dense even when technical coverage is PASS.	Fit must be solved through zone sizing, frame expansion, or layout choice, not font shrinking or text truncation.	T27 and T30

MDX 04

A. Original MDX contains	B. Current pipeline sees	C. Expected result	Gap owner
## 1 with several perception/problem groups.	Step 06 selects pre_construction_model_info_stacked with a reject/provisional path. Step 20 marks design readiness as needs_review.	Reject/provisional candidates must remain visible as candidates, but the slide should surface that adaptation is required.	T26 candidate policy
## 2 with ### 2.1 and ### 2.2, plus details blocks.	Step 06 keeps parent 04-2 and selects bim_issues_quadrant_four; earlier runs showed child handling instability.	Child groups under 04-2 should become internal quadrant/list items in source order.	T25 slot mapping
Content is larger than the currently chosen zones in some layouts.	Technical PASS does not guarantee presentation readiness.	The system should resize/replan zones or expand frame structure. It must not shrink font size to hide overflow.	T24/T27/T30

MDX 05

A. Original MDX contains	B. Current pipeline sees	C. Expected result	Gap owner
Two top-level numbered sections, 05-1 and 05-2.	Step 06 now emits two units, but both use three_parallel_requirements through generic_fallback. Step 20 marks design readiness as not_ready.	Sections must stay separated, and fallback/generic frames must be visible as not ready unless a real matching/adaptation path is used.	T24/T26
05-2 uses numeric ### 1 and ### 2 headings, not decimal ### 2.1 style headings.	These child headings are raw section content.	The contract must decide whether numeric child headings are allowed input or require MDX standardization.	T21.6/T22
User-selected alternative frames can work through CLI override, but UI selection has not been proven.	data/user_overrides/05.json contains zone assignment but no frames override.	Frontend frame selection must persist frames and backend must apply the selected frame without stale preview or silent no-op.	T28 frontend override E2E

Aggregate Node Inventory

Node type	Found in	Current state	Contract decision needed
pre_intro	MDX 01	Not promoted to a unit	Allow as first-class unit or require source standardization
numbered_section	MDX 01-05	Parsed as top-level units	Keep as the main slide-zone unit type
subsection_decimal	MDX 02, 03, 04	Usually raw content under parent	Map to frame-internal groups unless explicitly split
subsection_numeric	MDX 05	Raw content under parent	Decide whether allowed or normalized to decimal form
component_ref	MDX 02 <DxEffect />	Opaque tag	Registry-based component expansion
image_ref	MDX 01, MDX 02	Asset copy now works for known frame images; content images still need typed handling	Explicit image node and image slot policy
details_popup	MDX 01, MDX 04	Raw markdown/html-like content	Explicit popup/details node and presentation policy
table_like_content	MDX 01 details, MDX 02 component, MDX 03 table	Partly raw content	Explicit table/comparison nodes
summary_footer	All five MDX samples conceptually	Must stay outside body frame zones	Fixed base-slide region, not a body layout zone

Aggregate Gap List

Gap	Evidence	Next task
Pre-intro content lacks stable unit identity	MDX 01 source has visible content before the first ##; Step 02 emits only 01-1 and 01-2; override references orphan 01-3	T22
Registered component expansion does not exist	MDX 02 uses <DxEffect />; current parser sees only the component tag	T23
Child headings need frame-internal mapping	MDX 02/03/04/05 child headings remain raw content or map inconsistently	T25
Generic fallback can be technically PASS but design-not-ready	MDX 05 uses generic_fallback for both units	T26/T30
Frontend override persistence is not proven	MDX 05 override JSON has no frames; CLI override works separately	T28
Fit is still a structure/layout problem, not a font problem	MDX 03/04 can be dense; policy forbids font shrinking	T24/T27/T30

Immediate Contract Decisions For T21.6

1. Unit identity policy:
   • Prefer stable explicit ids such as 01-intro, not implicit renumbering.
   • Existing user override aliases such as 01-3 need a tested migration or compatibility rule.
2. Component registry:
   • Start with DxEffect.
   • New components must be added through registry entries, not one-off parser branches.
3. Child-section policy:
   • Top-level ## n. sections map to body zones.
   • Child headings map to internal frame slots by default.
4. Allowed input policy:
   • ## n. Title is allowed.
   • Registered component tags are allowed.
   • Unregistered component tags are unsupported.
   • Raw JSX/style blobs are disallowed in rendered text and must be sanitized or rejected.
5. Coverage-state policy:
   • covered_native: current frame and builder can render source atoms verbatim.
   • covered_via_expand: current frame can render after deterministic repeat/expand.
   • requires_adaptation: visual motif is usable, but an adapted schema is needed.
   • unsupported: no current contract path; must be surfaced honestly.