C.E.L_Slide_test2/docs/architecture/PHASE-Z-MATCHING-ARCHITECTURE.md

Phase Z 매칭 아키텍처 — 원칙 anchor

22-step pipeline 의 매칭 layer (Step 5/6/7 + B-axis Step 9/10/11) 를 다루는 원칙 anchor doc.

본 문서는 새 디자인 생성 이 아니라 기존 코드 / 과거 docs / 관찰 사례 / session 인사이트 를 근거로 한 forward improvement consolidation.

관련 anchors :

• docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (D1, 22-step pipeline)
• docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md (D2, Layer A/B SPEC)
• docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-PLAN.md (D3, schema completion plan)
• docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (D4, 현재 status)

§0. 본 문서의 작성 방법론 (P0)

evidence-based forward improvement — 매번 4 source 를 거쳐 도출 :

1. 과거 docs (D1 / D2 / D3 / D4) — 원래 의도
2. 현재 코드 (src/phase_z2_*.py / templates/phase_z2/catalog/frame_contracts.yaml) — 실제 동작
3. 관찰된 혼선 / 실패 사례 — 경험적 evidence
4. session 인사이트 — 최근 정리된 mental model

이걸 관찰 → 혼선 → 도출 원칙 → 개선 방향 form 으로 표면화. 과거 회귀 가 아니라 과거를 근거로 한 개선. 감으로 결정 / 가장 쉬운 선택 금지.

§1. 현재 코드 상태 (관찰)

1.1 매칭 단위 — CompositionUnit

매칭의 atomic unit 은 section 이 아니라 CompositionUnit. src/phase_z2_composition.py 의 collect_candidates 가 3 종 candidate type 을 동시 생성 :

• single — src/phase_z2_composition.py:230-243 (1 section 단독)
• parent_merged — src/phase_z2_composition.py:260-273 (parent 자체가 V4 매칭, children 묶음)
• parent_merged_inferred — src/phase_z2_composition.py:352-368 (children rep_match 기반 inferred merge)

각 candidate 는 source_section_ids[] + merge_type (line 232 / 262 / 354) 로 어떤 section 들을 어떻게 묶었는지 표현.

1.2 frame 선택 — render path authority = V4 rank-1

현재 render path 의 frame_template_id 는 composition planner 의 V4 rank-1 기반 :

• lookup_v4_match() in src/phase_z2_pipeline.py (D1:212 명시) — rank-1 만 반환
• composition planner 가 V4 결과로 candidate 생성

B4 (src/phase_z2_placement_planner.py:90-107 의 _select_frame) 도 frame selection 을 수행 하지만 trace-only — render path authority 는 V4 rank-1.

V4 = top-k 선언만 됐고 rank-1 사용 만 활성. D4 의 ⚠ partial.

1.3 binding — phase_z2_mapper.map_with_contract (Layer 1)

src/phase_z2_mapper.py:584-609 의 map_with_contract(section, contract) 는 contract 에서 오직 두 field 만 read :

• contract["source_shape"] (split 규칙)
• contract["payload"]["builder"] (named PAYLOAD_BUILDERS dispatch)

accepted_content_types / sub_zones 등 Layer 2 field 는 접근 X. 즉 mapper 는 Layer 1 binder 로 격리.

1.4 placement — phase_z2_placement_planner (Layer 2 reader, trace-only)

src/phase_z2_placement_planner.py :

• _select_frame (90-107) — accepted_content_types ⊇ content_type_set cover + declaration order first
• _assign_region_to_sub_zone (113-151) — sub_zones 의 narrowest-accepts first
• plan_placement (157+) — Stage A (B2 internal regions) + Stage B (region ↔ sub_zone) 통합

B4 는 Layer 2 reader 이지만 src/phase_z2_pipeline.py:1060-1145 에서 trace-only 로만 호출. render path (slot_payload 생성) 미연결. D4:78-83 의 render path placement_trace 미사용 과 일치.

1.5 capacity / fit — classifier (post-render telemetry)

src/phase_z2_classifier.py 의 classify_visual_runtime_check — render 후 visual measurement 기반 fit 판정. Architectural reframe (D2:16-33 의 PLANNING / RENDER / POST-RENDER 3-layer) : A1~A4 = post-render telemetry layer. 덜 중요 가 아니라 위치가 다름. 매칭 결정 자체에는 직접 입력 X (현재).

§2. 확인된 혼선 (resolution)

2.1 Sub-zone 용어 4-방향 충돌 → 4-tier 분리 (P5'')

session 안 누적 혼선 :

• D1 의 "Zone (top / bottom_l / bottom_r 등)"
• composition.py 의 child unit 분리 (single / parent_merged 등)
• yaml 의 sub_zones field
• 사용자 mental model 의 "### split"

→ 4 tier 별 명칭 lock :

Tier	명칭	위치	정체
1	Layout	slide-level	slide-body 안 zone topology (8-preset vocabulary)
2	Zone	layout 안	콘텐츠 구역 (top / bottom_l / bottom_r 등). 1 frame 매칭 단위
3	Split Zone (Child Unit)	zone 안	composition planner 가 만든 child unit (parent_merged 의 분리 단위)
4	Frame Slot	frame 안	yaml 의 sub_zones = Layer B placement target. region 매칭 대상

이후 본 문서 / 후속 doc 은 위 명칭 어휘 만 사용. yaml field sub_zones 는 기존 이름 유지하되 의미 = Frame Slot 으로 lock (mechanical rename 은 D3 plan).

2.2 composition tie-break ≠ Frame Slot tie-break

scope-lock 단계에서 D2:524-533 의 tie-break 을 composition tie-break evidence 로 잘못 분류. 실제로는 :

• D2:524-533 = Frame Slot 단위 tie-break (Stage B 안, frame 이미 선택된 후)
• composition tie-break = composition.py:433-441 (sort + greedy + coverage)

두 layer 가 다름. P7 evidence 는 composition layer 만, Frame Slot layer 는 별개 location.

2.3 "Layer 2 미사용" framing 오류

scope-lock 초안의 "mapper 가 Layer 2 를 consume 안 함" framing 은 암묵적으로 mapper 가 Layer 2 reader 가 돼야 한다 의 fix direction 함의. 실제 architectural intent :

• mapper = Layer 1 binder (의도된 격리)
• B4 = Layer 2 reader (의도된 분리)

문제 는 Layer 2 unconsumed 가 아니라 B4 의 Layer 2 read 가 trace-only 라 render path 까지 안 닿음. bridge 가 답이지 mapper 확장 이 아님.

2.4 Step 4/5/9 분리 미완

현재 구현은 D1 이 의도한 Step 4 → Step 5 → Step 9 분리가 완성되지 않음 :

• Step 4 (composition planning input — section_layout_signature / content_object 구조) = partial/dormant (D4:73 의 ⚠ partial transition)
• Step 5 evidence 와 Step 9 final selection = conflate (D1:255)

D1:185 가 명시적으로 Step 4 가 frame matching 보다 먼저 와야 함 을 지적.

§3. 도출된 원칙

P1 : 매칭 단위 = CompositionUnit (section 아님)

• 근거 : composition.py:230-243 (single) / :260-273 (parent_merged) / :352-368 (parent_merged_inferred). 각 line :232 / :262 / :354 가 merge_type signal
• 함의 : MDX section 을 1:1 zone 매칭 단위로 가정하는 코드 / doc 는 모두 추상화 누락. CompositionUnit 으로 통일.

P3 : frame 선택 / content binding layer 분리

• 근거 : 현재 코드의 de facto 분리 (mapper §1.3 + placement_planner §1.4)
• 원칙 : frame 선택 (어떤 frame 을 쓸지) 과 content binding (선택된 frame 에 콘텐츠를 어떻게 채울지) 는 별개 axis. 함께 결정하면 search space 가 곱셈으로 폭발 + 실패 격리 불가.
• 함의 : 어떤 axis 가 frame 을 결정 하는지 + 어떤 axis 가 binding 하는지 명시적 분리 — 한 module 이 둘 다 하면 회귀 위험.

P5'' : 4-tier terminology lock

§2.1 표 그대로. 후속 doc / commit message / 코드 docstring 모두 4-tier 어휘만 사용.

P7 : candidate-based composition (sequential A/B 아님)

• 근거 :
  • 원리 : docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md:216-218 ("child 따로 / sibling 묶기 / parent 단위" + scoring inputs)
  • 구현 : composition.py:230-243 / :260-273 / :352-368 (3 candidate type 동시 생성)
  • 선택 : composition.py:433-441 ((score desc, source_section_ids count desc) + greedy covered skip)
• 원칙 : composition 은 "## → fail → ### split → re-merge" sequential 이 아니라 3 candidate type 을 동시 생성 → score + coverage tie-break 의 parallel evaluation.
• D2:524-533 은 Frame Slot tie-break (Stage B) 로 본 P7 evidence 와 별도 layer.

P8 : staged migration — frame 선택 authority + binding 진화 분리

P8-a (near-term)

• 목표 : frame selection authority 정리 (V4 rank-1 단독 → B4 informant 또는 B4-mediated 의 어떤 형태)
• 유지 : mapper binding channel (PAYLOAD_BUILDERS) — 현재 working channel 안전
• open : B4 결과를 render path frame selection 에 어떻게 반영 할지의 bridge 형태 → §5 의 Q-V4B4 / Q-LB 에서 별도 scope-lock

P8-b (longer-term, 지금 결정 X)

• region / Frame Slot-aware slot_payload 진화
• PLACEMENT_PAYLOAD_BUILDERS 등 별도 namespace 가능성
• DC2 Open question (Q-LB) 해결 후 결정. 본 문서 시점에서는 deferred.

§4. 코드 변경 결정 지점

DC1 : Step 4/5/9 분리 미완

• 현 상태 : D1 의도한 Step 4 → Step 5 → Step 9 분리가 완성되지 않음. Step 4 (composition planning input — section_layout_signature / content_object 구조) 는 partial/dormant (D4:73 의 ⚠ partial), Step 5 evidence 와 Step 9 final selection 은 conflate (D1:255).
• 결정 지점 :
  • Step 4 가 frame matching 전 에 composition candidate 평가 input 으로 흘러야 (D1:185 명시적 지적)
  • Step 5 evidence layer 와 Step 9 final selection layer 의 명시적 분리 필요
• 영향 module : src/phase_z2_pipeline.py orchestrator + src/phase_z2_composition.py (input 확장)

DC2-a : phase_z2_mapper = Layer 1 working channel

• 현 상태 : src/phase_z2_mapper.py:584-609 가 source_shape + payload.builder 만 read. 현재 render path 의 유일 working channel.
• 결정 지점 : Layer 1 격리 유지. mapper 에 Layer 2 read 를 추가하는 방향은 반대 — 실제 의도는 별 axis (DC2-b + Open question Q-LB).

DC2-b : phase_z2_placement_planner = Layer 2 reader, render path 미연결

• 현 상태 : src/phase_z2_placement_planner.py:90-107 (accepted_content_types) + :113-151 (sub_zones) — Layer 2 read 활성. 그러나 src/phase_z2_pipeline.py:1060-1145 에서 trace-only. final render 미연결.
• 결정 지점 : Layer 2 read 결과를 render path 에 어떻게 합류시킬지 의 bridge 결정 — §5 의 Q-LB 에서 별도 scope-lock.

DC3 : Internal Region runtime — trace-only partial

• 현 상태 : SPEC v1 (D2) 가 Internal Region (Layer A) / Frame Slot (Layer B) 의 layered placement 정의. Layer A runtime 은 trace-only partial — src/phase_z2_placement_planner.py:157+ 의 plan_placement 가 Stage A 호출 (:192-197 의 plan_internal_regions call) 수행하지만, 결과가 render path 미합류. 부재 가 아니라 render path authority 미연결. D4:73 의 ⚠ partial 분류와 일치.
• 결정 지점 : Layer A planning telemetry 활성 단계 → render path 합류 단계의 separate axis. P8-b 와 연관 (slot_payload 진화 이전 단계).

§5. open scope-lock questions

본 axis 범위 밖 의 deferred 결정. 후속 axis 에서 각각 별도로 lock.

Q-FW : 4 filter score weight / threshold

• F1 frame internal fit / F2 child frame divergence / F3 content type-structure match / F4 content loss risk 의 score weight 와 auto vs review threshold 결정 필요.

Q-CO : candidate priority tie-break

• composition.py:433 의 (score, source_section_ids count) 외에 추가 axis (cardinality_fit / hierarchy_coherence / density) 도입 시점.

Q-RT : review / adapter_needed threshold

• W1/W2/W3 신호 + auto_selectable=False candidate 의 review surface 정책.

Q-V4B4 : V4 → B4 frame selection authority transition timing

• P8-a 의 언제 — V4 단독 / B4 informant / B4-mediated 의 단계.

Q-LB : Layer 1 ↔ Layer 2 bridge architecture

• DC2-b 의 어떻게 — mapper direct consume / B4-mediated integration / 별도 translator. Q-V4B4 와 연관되나 별개 layer (frame 선택 timing vs Layer 2 → render path bridge 구조).

Q-CE : catalog extension surface

• frame_contracts.yaml 에 신규 frame 추가 시 어떤 layer 부터 채워야 self-consistent 인지의 declarative form.

Q-DT : decision trace 표준 form

• composition / placement / fit_classification 의 trace 통합 schema. 현재 각각 다른 dict 구조.