kyeongmin
2ec8fc5a77
- add Internal Region model to Phase Z architecture docs and specs - add frame contract content type and Frame Slot declarations - add dormant content object extractor and internal region planner
17 KiB
17 KiB
Phase Z — composition planning schema plan (Layer A + Layer B)
Status : v1 plan (2026-04-30 refactor — SPEC v1 의 Layer A + Layer B 구조 반영). schema 작업 범위 / 순서 / 완료 기준 정의. 구현 X.
Anchor : PHASE-Z-PIPELINE-STATUS-BOARD.md 의 핵심 missing — Step 3 / 4 / 11 + Step 10 (부분).
v0 → v1 변경 요약
- SPEC v1 의 renumbered section 으로 cross-reference 일관 갱신 (§1 / §2 신규 / §3 / §4 / §5 …)
- Step 4 의 schema 가 SPEC v1 §2 (Internal Region — Layer A) 로 이미 정의됨 → 본 plan 에서는 신규 작성 이 아니라 완성도 점검 으로 전환
- Step 11 의 schema 가 SPEC v1 §4 (2-stage placement: Stage A → Stage B) 로 재정의됨에 따라 validation 기준 보강
- mechanical rename :
sub_zone→Frame Slot(PLAN 본문). YAML 필드명sub_zones는 코드 reality 로 유지- 4 step 범위 (Step 3 / 4 / 10-partial / 11) 그대로. Step 10 의 density envelope 제외 그대로
- implementation / MDX 실행 검증 / AI 호출 / 파일명 변경 / code marker 이름 결정 — 모두 제외 그대로
0. 문서 역할 분리
| 문서 | 역할 |
|---|---|
PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md (v1) |
schema / contract 명세 자체 (authoritative) |
본 문서 (PHASE-Z-CONTENT-OBJECT-SUBZONE-PLAN.md) (v1) |
그 schema 작업을 어떤 범위 / 순서 / 산출물 / validation 기준 으로 진행할지 계획 |
본 plan 은 SPEC 을 대체하지 않음. SPEC 의 어느 section 이 어느 step 의 schema 인지 cross-reference + 완성도 점검 까지가 본 plan 의 영역.
1. 목적
일반 MDX 1 파일이 render 전 단계 에서 typed content_object → Internal Region → Frame Slot 으로 결정 가능한 상태에 도달하도록, 다음 4 step 의 schema 정의를 완결 시킨다.
Step 3. Content Object 추출
Step 4. Section Internal Composition Planning (Layer A)
Step 10. Frame Contract 의 accepted_content_types + Frame Slot 선언 (부분, Layer B)
Step 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping (2-stage)
2. 범위
2.1 포함
| Step | schema 항목 | SPEC v1 의 위치 |
|---|---|---|
| Step 3 | content_object base schema + 6 type 별 schema (text_block / table / transform_table / image / diagram / details) | SPEC v1 §1.1, §1.2 |
| Step 3 | role 의미 (summary / detail / decorative / reference) | SPEC v1 §1.3 |
| Step 4 | Internal Region entity schema (region_id / role / content_type / ratio_estimate / content_unit_ids / frame_match_strategy) | SPEC v1 §2.1 |
| Step 4 | Universal Region Model (every zone = 1+ regions) | SPEC v1 §2.2 |
| Step 4 | 3-way decision tree (whole / group / split) | SPEC v1 §2.3 |
| Step 4 | region 비율 산정 (content type 별 size proxy) | SPEC v1 §2.4 |
| Step 4 | region → frame / display 매칭 interface (frame_match / display_only) | SPEC v1 §2.6 |
| Step 10 | frame contract 의 accepted_content_types 필드 schema |
SPEC v1 §3.1 |
| Step 10 | Frame Slot 선언 schema (YAML 필드명 sub_zones — 의미 = Frame Slot) |
SPEC v1 §3.1 |
| Step 10 | F13 / F29 / F16 의 Frame Slots 선언 예시 | SPEC v1 §3.2 |
| Step 11 | placement algorithm 2-stage I/O schema | SPEC v1 §4.1 |
| Step 11 | Stage A — content → Internal Region (Layer A 매핑) | SPEC v1 §4.2 |
| Step 11 | Stage B — Internal Region content → Frame Slot (Layer B 매핑) | SPEC v1 §4.3 |
| Step 11 | tie-break (Frame Slot 단위) | SPEC v1 §4.4 |
| Step 11 | display_only region 처리 (frame 우회) | SPEC v1 §4.5 |
| Step 11 | display_strategy schema (inline_full / inline_preview_with_details / details_only / dropped) | SPEC v1 §5.1, §5.5 |
| Step 11 | display_strategy 의 region-level + slot-level 양쪽 적용 | SPEC v1 §5.3 |
2.2 Step 10 의 부분 범위 명시 (불변)
본 plan 에서 Step 10 은 두 항목 까지만 다룸 :
accepted_content_types- Frame Slot 선언 (YAML 필드명
sub_zones)본 plan 에서 다루지 않는 Step 10 항목 :
density envelope
density envelope은frame_internal_fit_candidate(Step 17 / Step 19 Gap) 와 연결된 frame internal fit policy 영역. 본 plan 에 넣으면 공통 padding 축소 antipattern (feedback_phase_z_spacing_direction) 과 섞일 risk 있어 별 plan 으로 분리.따라서 본 plan 이 완료되어도 Step 10 전체가 ✅ 완료되는 것은 아니고 —
accepted_content_types+ Frame Slot 부분만 ✅ / density envelope 부분은 ❌ 잔존.
2.3 명시적 제외
- 구현 (extractor / planner / parser 코드 작성) — 본 plan 은 schema 까지
- frame partial template 변경 (Frame Slot / region container marker 추가)
- mapper / classifier 의 region / Frame Slot-aware 진화
- details / popup runtime
- backward flow 자동화 (telemetry → composition 재호출)
- MDX 01 / 02 / 03 / 04 적용 검증
- AI 호출 (plan 단계 자체 + plan 산출 schema 자체 모두)
- code / module / HTML marker / attribute 이름 결정 (SPEC v1 와 동일 — implementation step 에서 결정)
- 파일명 변경 (PLAN / SPEC 둘 다 — 향후 별 결정)
- 다음 단계 우선순위 / A/B/C 선택지
3. 산출물
3.1 schema-side 산출물
본 plan 의 schema 작업이 완료되면, SPEC v1 가 다음 상태에 도달 :
| schema | 현재 SPEC v1 상태 | plan 종료 후 목표 상태 |
|---|---|---|
| content_object base + 6 type 별 schema | draft (SPEC v1 §1.1, §1.2) | completeness reviewed + gaps listed |
| role 의미 4 종 | draft (SPEC v1 §1.3) | completeness reviewed + gaps listed |
| Internal Region entity + Universal Region Model | draft (SPEC v1 §2.1, §2.2) | completeness reviewed + gaps listed |
| 3-way decision tree | draft (SPEC v1 §2.3) | completeness reviewed + gaps listed |
| region 비율 산정 | draft (SPEC v1 §2.4) | completeness reviewed + gaps listed |
| region → frame / display 매칭 interface | draft (SPEC v1 §2.6) | completeness reviewed + gaps listed |
| accepted_content_types + Frame Slot 선언 | draft (SPEC v1 §3.1, 3 frame 예시 §3.2) | completeness reviewed + gaps listed |
| 2-stage placement (Stage A + Stage B I/O) | draft (SPEC v1 §4.1, §4.2, §4.3) | completeness reviewed + gaps listed |
| tie-break + display_only region 처리 | draft (SPEC v1 §4.4, §4.5) | completeness reviewed + gaps listed |
| display_strategy 4 종 + region/slot 양쪽 적용 | draft (SPEC v1 §5.1, §5.3, §5.5) | completeness reviewed + gaps listed |
3.2 plan-side 산출물
- 본 PLAN 문서 (v1) — schema 작업 범위 정의
- 작업 결과로 SPEC v1 의 추가 / 수정 부분 (edge case 보강 등 — substantive 신규 schema 가 아닌 점검 결과)
- pipeline data flow 위치 표 (§5 참조)
- schema validation 기준 표 (§6 참조)
4. SPEC ↔ PLAN cross-reference
본 plan 의 4 step 각각이 SPEC v1 의 어느 section 으로 매핑되는지 :
| Step | SPEC v1 section | plan 에서의 작업 |
|---|---|---|
| Step 3 | §1 (content_object schema) | 완성도 점검. nested_list / sub-decomposition edge case (SPEC v1 §9.2 미해결 부분 — text_block 의 nested 구조를 sub_text_block 으로 sub-decompose vs Frame Slot cardinality aggregate 해석) |
| Step 4 | §2 (Internal Region schema, Layer A) | 완성도 점검. 3-way decision 의 boundary 케이스 / region 비율의 fallback / frame_match_strategy 가 unknown / ambiguous 일 때 거동 |
| Step 10 (partial) | §3.1 (schema) + §3.2 (3 frame 예시) | 완성도 점검. density envelope 미포함 명시 |
| Step 11 | §4 (placement algorithm 2-stage) + §5 (display strategy) | 완성도 점검. Stage A → Stage B interface 정합 (Stage A 의 frame_match_strategy 가 Stage B 의 입력으로 자연 호환) / backward flow 자동화 X 등 v1 한계 재확인 |
5. Pipeline data flow 위치
본 4 step 의 schema 가 어디서 생성 / 누가 소비 하는지.
Step 1 MDX 업로드
↓
Step 2 MDX 정규화 (section / heading / raw_content 분리)
↓
├─→ Step 3. Content Object 추출
│ INPUT : section.raw_content (markdown 문자열)
│ OUTPUT : section.content_objects = [ContentObject ...]
│ SCHEMA : SPEC v1 §1
│ 소비자 : Step 4, Step 11
│
└─→ Step 4. Section Internal Composition Planning (Layer A)
INPUT : section.content_objects (from Step 3) + section metadata + V4 evidence
OUTPUT : zone.internal_regions = [
{region_id, role, content_type, ratio_estimate,
content_unit_ids, frame_match_strategy}, ...
]
SCHEMA : SPEC v1 §2 (entity / Universal Region Model / 3-way decision / 비율 / interface)
소비자 : Step 6 (composition planning) / Step 8 (region ratio) /
Step 9 (region-level frame match) / Step 11 (Stage A 결과)
Step 5 Matching Evidence 생성 (V4 top-k)
Step 6 Composition Planning (Step 4 region 분할 결과 입력)
Step 7 Slide-Level Layout Planning
Step 8 Zone + Internal Region Ratio Planning (region 비율 = Step 4 산출)
Step 9 Region-Level Frame / Display Selection (region 별 frame_match_strategy = Step 4 산출)
↓
└─→ Step 10 (partial). Frame Contract 확인
INPUT : selected frame_id (region 별)
OUTPUT : frame_contract.accepted_content_types
+ frame_contract.sub_zones (= Frame Slots, Layer B)
SCHEMA : SPEC v1 §3
소비자 : Step 11 (Stage B)
↓
└─→ Step 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping (2-stage)
INPUT : section.content_objects (from Step 3)
+ zone.internal_regions (from Step 4)
+ frame_contract.sub_zones (= Frame Slots) (from Step 10, frame_match region 만)
Stage A : content → Internal Region (Step 4 의 region 분할 결과 소비)
Stage B : Internal Region content → Frame Slot (frame_match region 만 진입)
display_only region → display strategy 처리 (Stage B 우회)
OUTPUT : placement = {
internal_regions: [
{..., slot_assignments[], overflow_buffer[], rejection[]}, ...
]
}
SCHEMA : SPEC v1 §4 + §5
소비자 : Step 12 (slot payload 생성, region + Frame Slot 단위 grouping)
Step 12 Slot Payload 생성
Step 13 Render
...
6. schema validation 기준
validation = schema 자체의 구조 검증 까지만. 실제 MDX 적용 검증 X (sample budget rule).
6.1 Step 3 — content_object schema
- base schema 의 모든 필수 필드 (id, type, role, size_estimate, raw_payload, type_specific) 정의됨
- 6 type 모두 type_specific schema 있음 (text_block / table / transform_table / image / diagram / details)
- role 4 종 (summary / detail / decorative / reference) 정의됨
- role 별 fallback 거동 (decorative drop / detail → details escalate / summary·reference rejection) 명시됨
- 원문 raw_payload 보존 룰이 schema 에 포함됨 (자름 / 변형 X)
6.2 Step 4 — Internal Region schema (Layer A)
- Internal Region entity 의 모든 필수 필드 (region_id, role, content_type, ratio_estimate, content_unit_ids, frame_match_strategy) 정의됨
- Universal Region Model 명시 (every zone has 1+ regions / single-region for text-only / multi-region for mixed-content)
- 3-way decision tree 의 3 분기 (whole-section frame match / child-section grouping / content-type split) 가 결정론적 함수 로 표현됨 (AI 판단 X)
- 각 분기의 판단 기준 (cardinality / accepted_content_types / heading depth + content 구조) 명시됨
- region 비율 산정의 size proxy (text_block: line_count / table: rows × line_height / transform_table: pair_count × pair_height / image: aspect_ratio / details: summary line_count) 정의됨
- zone 내 region ratio 합 = 1.0 normalize 룰 명시됨
- frame_match_strategy 의 두 kind (frame_match / display_only) 정의됨
- display_only path 가 frame contract 없이 동작 가능함이 명시됨
- decision 이 unknown / ambiguous 일 때의 fallback 명시됨
6.3 Step 10 (partial) — frame contract schema (Layer B 선언)
accepted_content_types필드 schema 정의됨 (list of type 이름)not_accepted필드 schema 정의됨 (디버그용)- Frame Slot 선언 schema 정의됨 (id / role / accepts / cardinality / partial_target_path) — YAML 필드명
sub_zones, 의미 = Frame Slot - cardinality 표현 방식 (
strict또는min/max) 정의됨 - F13 / F29 / F16 3 frame 의 Frame Slot declaration 예시 완비
- density envelope 미포함 이 schema 위에 명시 주석으로 박혀 있음
6.4 Step 11 — placement (2-stage) + display_strategy schema
- placement algorithm 2-stage I/O schema 정의됨 (input + Stage A 출력 + Stage B 출력)
- Stage A schema 정의됨 (content_object → Internal Region 매핑 결과 + frame_match_strategy 결정)
- Stage B schema 정의됨 (Internal Region content → Frame Slot 매핑 결과 — frame_match region 만)
- sorting / type 매칭 / cardinality 적용 / role 우선순위 / tie-break 의 결정론적 룰 (Stage B) 명시됨
- display_only region path 의 display_strategy 매핑 정의됨 (image area / table preview / details button / diagram inline)
- 6 type × 3 escalation (inline / preview+details / popup-only) 매트릭스 정의됨
- display_strategy 4 종 (inline_full / inline_preview_with_details / details_only / dropped) 정의됨
- display_strategy 가 region-level + slot-level 둘 다 적용됨이 명시됨
- AI 호출 X + 원문 손실 금지 룰이 schema 위에 명시됨
- backward flow 자동화 X (v1 한계) 가 schema 위에 명시됨
6.5 통합 validation
- Step 3 → Step 4 의 type 호환 — content_object.type 이 Internal Region.content_type 으로 결정론적 매핑
- Step 3 → Step 11 (Stage B) 의 type 호환 — Step 3 의 모든 type 이 어딘가 frame.accepted_content_types 에 등장 가능 (또는 명시적 reject) 또는 display_only path 로 처리 가능
- Step 4 → Step 8 의 ratio 호환 — Internal Region.ratio_estimate 가 Step 8 의 region-level ratio 입력으로 호환
- Step 4 → Step 9 의 frame_match_strategy 호환 — Step 9 의 region-level frame 매칭 입력으로 호환
- Step 4 → Step 11 (Stage A) 의 region 분할 호환 — Stage A 가 Step 4 의 internal_regions 를 재계산하지 않고 그대로 소비
- Step 10 의 cardinality 가 Step 11 Stage B 의 placement algorithm 이 소비 가능한 형태
7. AI 원칙
- 본 plan 작성 / schema 정의 단계 — AI 호출 없음
- runtime AI = Step 12 의 light_edit / restructure 의 content_object → Internal Region / Frame Slot proposal 1 곳만
- Step 0 (Figma → HTML 변환 등 사전 준비) 의 AI 사용은 precondition phase 로, runtime AI 가 아님
8. 금지
- 구현 금지 (extractor / planner / parser 코드 작성)
- render 변경 금지
- frame partial 변경 금지 (Frame Slot / region container marker 추가 미포함)
- mapper / classifier 의 region / Frame Slot-aware 진화 금지
- details / popup runtime 작성 금지
- MDX 01 / 02 / 03 / 04 실행 금지
- AI 호출 금지
- code / module / HTML marker / attribute 이름 결정 금지 (SPEC v1 와 동일 — implementation step 에서 결정)
- 파일명 변경 금지
- next step 추천 금지
- 우선순위 결정 금지
- A / B / C 선택지 제시 금지
9. 본 plan 의 보존 / 변경 정책
- 본 plan 은 schema 작업 범위 + 완료 기준 의 기준점. schema 작업 진행 중 새로운 edge case 발견 시 본 plan 의 6 절 (validation 기준) 에 항목 추가 형태로 갱신
- 범위 확장 (예: Step 7 추가, density envelope 포함, code marker 이름 결정 포함) 은 사용자 명시 잠금 후에만
- 본 plan 이 완료되면 STATUS-BOARD 의 :
- Step 3 → ⚠ partial (schema 정의 완료, 구현 미완)
- Step 4 → ⚠ partial (Layer A schema 정의 완료, 구현 미완)
- Step 11 → ⚠ partial (2-stage schema 정의 완료, 구현 미완)
- Step 10 → ⚠ partial (accepted_content_types + Frame Slot 부분 완료, density envelope 미포함 잔존)
- SPEC 의 추가 갱신 (edge case 보강 등) 은 본 plan 의 §3.1 목표 상태 (completeness reviewed + gaps listed) 의 자연 산출물