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
286 lines
17 KiB
Markdown
286 lines
17 KiB
Markdown
# 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`](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`](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) 의 자연 산출물
|