comp-frame 알고리즘
fallback 흐름과 의문점

comp-frame은 “내 글을 이미 있는 디자인의 어느 칸에 넣을까?”를 계산합니다. 예를 들어 세 단계의 설명을 담으려면, 세 장의 카드가 있고 각 카드에 제목과 본문을 넣을 수 있는 디자인이 필요합니다. 코드는 먼저 칸 배정을 연습하고, 사용할 수 있는 후보를 추린 뒤 순위를 매깁니다.

입력은 VisualSummary 문서입니다. title은 문서 제목, components는 디자인으로 표현할 내용 덩어리들의 목록입니다. 화면은 YAML과 JSON을 받으며 단일 Component도 문서로 감싸서 처리합니다. 전체 문서는 version과 올바른 결합 type 등 규약 검사를 통과해야 합니다.

version: "0.5"
title: "주문 진행 과정"
components:
  - type: "ProcessFlow.Steps"
    structure:
      entities:
        - label: "견적 제출"
          items: ["수량과 납기를 적습니다."]
        - label: "주문 확인"
          items: ["금액과 일정을 확인합니다."]
        - label: "제작 시작"
          items: ["확인된 주문을 제작합니다."]

여기에는 컴포넌트 1개, 항목 3개, 항목마다 제목 1개와 본문 1개가 있습니다. 컴포넌트 3개가 아니라, 하나의 컴포넌트 안에 카드 3개가 필요한 것입니다.

검색 결과는 아직 완성된 그림이 아닙니다. 화면이 이 결과를 받아 원본 디자인을 로딩하고 binding의 글을 넣어 썸네일을 만듭니다. 그래서 “검색 통과”와 “실제 이미지에서 읽기 좋음”은 별도로 확인해야 합니다.

코드 근거 · 입력 파싱 · 문서별 검색 · 결과 구조

Frame은 “칸을 기록한 표”라고 생각하면 됩니다. 입력 쪽은 각 칸에 넣을 글을 적고, 디자인 쪽은 그 글을 받을 실제 노드 주소와 용량을 적습니다. 같은 모양의 표를 쓰기 때문에 서로 비교할 수 있습니다.

입력 Frame은 그때 만들고, 디자인 Frame은 미리 만들어 둡니다

buildQueryFrames는 검색할 때 입력을 복제하고 관계 ID를 해석한 뒤 카테고리별 Frame을 만듭니다. 관계가 존재하지 않는 항목을 가리키면 실패를 돌려줍니다. buildIisFrame은 I.I.S.가 인식한 항목·필드를 실제 RLSC 노드에 연결하고, 적절한 I.I.S. 구조가 없으면 로더가 buildRuleFrame으로 반복 모양을 추정합니다.

코드 근거 · Frame 버전·타입 · I.I.S. Frame · 규칙 Frame · 별칭과 중복 노드

단계 설명을 Steps로 표현하고 싶어도, 공급된 디자인 중 적당한 Steps가 없을 수 있습니다. 이때 규약이 허용하는 다른 카테고리를 차례로 찾습니다. 카테고리가 내용을 받아들일 수 있는지는 establish, 실제 디자인에 글이 들어가는지는 나중의 배정·용량 검사가 판단합니다.

예를 들어 Steps의 행은 Timeline → Staircase → List입니다. 입력이 17항목이면 상한 15인 Timeline과 상한 8인 Staircase는 성립하지 않아 건너뜁니다. List가 이미 Tier 2에 들어갔다면 Tier 3에서 또 넣지 않습니다.

투영 P1~P7은 “다른 종류에서도 읽히게 내용의 자리를 바꾸기”입니다

현재 보정은 summary-projection.ts와 summary-content.ts에서 하며 벤더 eregion 코드는 그대로 둡니다. 현재 관계 변환은 desc만 남깁니다. “관계 종류·참가자도 함께 남긴다”는 일부 과거 문서와 주석은 최신 relationLines 본문과 다릅니다. 표 첫 열의 제목도 P4 텍스트 변환에는 남지 않습니다. 따라서 투영은 모든 의미를 무손실 보장하는 변환이 아닙니다.

코드 근거 · Tier 생성 · 종단 선택 · 자체 투영 보정 · 표 변환 · 관계 desc · 정본 P1~P7·P8 폐기

카테고리를 정했으면 후보 DB에서 대략 맞는 디자인을 가져옵니다. 모든 디자인을 렌더해 볼 수 없으므로, 먼저 값싼 조건으로 줄입니다. 이 필터를 통과한 후보만 정밀한 대치 검사를 받습니다.

비트는 스위치처럼 “그 역할이 어딘가에 있음/없음”만 기록합니다. 카드마다 칸 수나 위치·크기가 같은지는 모릅니다. 역할이 추가된 경우뿐 아니라 빠진 경우도 비트 차이에 포함됩니다. 한 카테고리에서 Stage 0·1·2는 서로 겹치지 않습니다.

m = overflow_multiplier (기본 1)
label_lines ≥ ceil(제목들의 최대 명시적 줄 수 / m)
label_cpl ≥ ceil(제목들의 최대 한 줄 길이 / m / 2)

코드 근거 · label 하한 · Stage 분리 · 필터 구성 · 허용 비트 · measure·matrix Frame

searchFrames 안에는 Tier → 카테고리 → Stage → 페이지 순서로 반복이 겹쳐 있습니다. “반복문이 있다”는 사실보다, 각 반복이 어떤 일을 하고 무엇을 세는지가 중요합니다.

한 페이지를 가져올 때 실제로 하는 일

1. 각 카테고리에서 Stage 0~2의 합집합을 count()로 센다. 이것은 정밀 검사 전 공급 수다.
2. 카테고리를 순서대로 처리한다. 현재 코드는 균등 배분하지 않는다. Tier 시작 때의 남은 목표로 카테고리 배정량을 정한다.
3. 페이지 요청량은 min(남은 스캔 예산, 남은 통과 목표, 1000)이다. 가져온 만큼 offset과 스캔 수를 증가시킨다.
4. 행 주소로 중복을 제거하고 그 행을 통과시킨 QueryFrame을 matchedQueries에 기록한다. 한 행이 여러 카테고리에 있어도, 실제로 통과한 질의로 채점한다.
5. 그 페이지의 아직 승인되지 않은 행을 rankCandidates(..., dedup:false)로 검사한다. 배정·내용·용량·속성 조건을 통과한 행 주소만 admittedKeys에 넣는다.
6. 전부 탈락했다면 다음 페이지 또는 Stage·카테고리·Tier로 계속 간다. 마지막에는 모은 전체 행을 다시 평가하고 정렬·fingerprint 중복 제거·top_n 절단을 한다.

작은 사례를 한 단계씩 따라가기

코드 근거 · 반복 진입·count · 카테고리·Stage·페이지 · 승인 수 갱신 · Tier 문턱 · 최종 재평가

큰 Steps 상자 안에 작은 BigNumber 카드가 있다고 합시다. 처음부터 두 개를 따로 찾으면 “수치가 어느 단계에 속하는지”라는 배치 정보가 사라질 수 있습니다. 그래서 현재는 전체 중첩을 지킬 수 있는지부터 확인합니다.

여기서 exactType은 “Stage도 0만”이라는 뜻이 아닙니다. 카테고리 Tier만 1로 제한하며, 같은 카테고리 안의 Stage 0·1·2와 용량·내용 검사는 여전히 실행됩니다. 또한 N 단계는 트리 전체가 한 번에 N1→N2→N3→N4→N5로 한 줄 이동하는 모습만 있는 것이 아닙니다. 벗겨진 한 조각이 다시 N1/N2로 성공하거나, 다른 조각보다 먼저 N5에 도달할 수 있습니다.

N2의 조합 순서를 손으로 써 보기

부모와 자식에 원형 0, 첫 대안 1, 둘째 대안 2가 있다고 합시다. N1은 (0,0)입니다. N2는 강등 칸수의 합이 작은 순서이며, 동점에서는 더 깊은 노드를 먼저 내립니다.

중간 카테고리가 성립하지 않아 빠져도 원래 행에서의 칸 거리는 유지합니다. 각 조합의 투영은 원본 노드에서 출발합니다. 바뀐 카테고리의 fallback을 다시 따라가며 무한히 돌아가는 방식이 아닙니다.

부모를 벗길 때도 규칙이 있습니다

• 부모 내용 이전(N-R1): 부모의 label·items·관계 desc 등 텍스트화한 내용을 첫 자식의 첫 entity.items 뒤에 붙입니다. 부모를 제거하는 것과 그 글을 지우는 것은 다릅니다.
• 연속 형제 묶음(N-R2): 4형제는 [4] → [3,1] → [2,2] → [2,1,1] → [1,1,1,1] 순서입니다. [1,3] 같은 모든 순서 있는 분할을 열거하는 알고리즘이 아닙니다. 이 비대칭은 규약에 정해진 선택입니다.
• Hierarchy 예외(N-R5): 현재 부모의 대분류가 Hierarchy면 N1/N2 실패 후 N3/N4를 건너뛰어 N5로 갑니다. 소속 계층이 사라지는 일을 피하려는 규칙입니다.
• 뿌리 없는 묶음: Unclassified를 검색 type으로 만들지 않습니다. forest의 바깥 Frame은 카테고리 없는 경계이며 내부 카테고리로 후보를 찾습니다.

코드 근거 · N2 선택지 · 조합 생성 · 부모 내용 이전 · N1/N2·첫 성공 · N3~N5 재귀 · exactType의 Tier 제한 · N 단계 규약

align은 첫 항목을 첫 카드에, 둘째 항목을 둘째 카드에 배정합니다. 모든 배치 조합을 탐색해 최적의 자리를 찾는 함수는 아닙니다. 같은 이름 → 별칭 → 다른 텍스트 칸으로 이동 순서로 글을 넣고, 그 결과를 costOf가 검사합니다.

제목 슬롯이 있으면 페이지 제목을 넣습니다. 제목 입력이 없으면 원래 제목을 보존하고, 부제·설명 위성은 보존합니다. 제목을 받을 슬롯이 없으면 titleDropped 벌점 1이며 contentLoss와는 다른 판정입니다. 화면의 경계 밖 제목 구제는 다음 절에서 따로 설명합니다.

용량은 “합친 글이 몇 줄인가?”로 검사합니다

줄바꿈 없는 73자는 한 줄 20자 기준으로 4줄입니다. 1.0배이면 4>3 또는 73>60이므로 탈락합니다. 1.5배에서는 4≤4.5이고 73≤90이므로 통과하며 용량 벌점 약 5.01점을 받습니다. 허용 배수는 검사 기준이며 실제 폰트 크기를 바꾸지 않습니다.

예상 줄 수 = 명시적 각 줄에 대해 max(1, ceil(UTF-16 길이 / 한 줄 용량))의 합
탈락 = 예상 줄 수 > cap.lines × m  또는  글자 수 > cap.chars × m
줄 벌점 = 4 × Σ sqrt(max(0, 예상 줄 수 − cap.lines))
글자 벌점 = 2 × Σ clamp((글자 수 / cap.chars − 1) / 0.43, 0, 1)

코드 근거 · 항목 배정 · 별칭 단계 · 위성 처리 · 내용 손실 배제 · 용량 게이트

벌점은 발생량 × 가중치를 더한 값이며 낮을수록 좋습니다. 빈 카드 1개가 10점, 다른 역할로 옮긴 필드 2건이 6점이면 두 항목의 합은 16점입니다. 그렇다고 최종 순위가 항상 총점 하나로 결정되지는 않습니다.

후보 하나의 순위는 사전식으로 비교합니다

장식은 점수를 더하지 않고 preferred → neutral → avoided 순서로 비교합니다. 기본 모드에서는 같은 fallback 위치 안에서 적용합니다. 코드상 tier_penalty에도 장식 비교가 비용보다 먼저 있으므로 “총점만으로 정렬”이라고 설명하면 틀립니다. 장식 축의 순서는 ornament, background이며 중첩도 비교 대상입니다.

동점은 template_idx 내림차순(NULL 마지막) → 디자인 ID 내림차순 → 노드 ID 오름차순입니다. 정렬 후 frame_fingerprint가 같은 결과를 합치고 top_n까지만 반환합니다. fingerprint가 NULL인 행은 이 중복 제거에서 합치지 않습니다.

코드 근거 · 18개 기본값 · 글꼴 위계 · 실제 정렬 순서 · 해석별 시도·첫 성공 · 중복 제거·top_n · 장식 순서

계산 결과와 그림 사이에는 화면의 처리가 한 번 더 있습니다. 이 층을 빼면 “blank인데 왜 글이 보이지?” 또는 “제목이 보이는데 왜 제목 탈락 벌점이 있지?”라는 질문에 답할 수 없습니다.

화면의 제목 구제는 같은 썸네일에 제목을 두 번 쓰지 않도록 이미 title binding이 있으면 생략합니다. 구제된 제목을 포함해 검색 점수를 다시 계산하거나 새 용량 게이트를 실행하지는 않습니다. forest Query Frame은 현재 위성 제목을 만들지 않는 경로도 있으므로, 제목이 각 단계에 실제로 남는지는 pageTitle → satellites.title → binding → 화면 지도를 따로 추적해야 합니다.

여러 조각이 나오면 한 페이지 후보 카드로 묶습니다

합산 방법을 보여 주는 계산 예시입니다.

조각이 하나면 결과마다 단일 카드를, 둘 이상이면 현재 선택한 후보들의 비용 합을 가진 그룹 카드 하나를 만듭니다. 그룹 Tier는 선택 결과 중 가장 큰 값입니다. 대안 선택을 바꾸면 비용·Tier를 다시 합쳐 목록을 정렬합니다. 가능한 모든 조합의 페이지를 자동 생성하는 것은 아닙니다.

색상·크기·간격의 조화는 이 비용 합에 포함되지 않습니다. 색상 대치와 선택적 재배치는 렌더 쪽 작업이며 이후 검색 점수를 다시 매기지 않습니다. N3/N4 조각을 새로운 한 장의 레이아웃으로 배치해 주는 엔진과, 화면에서 결과들을 그룹 카드로 보여 주는 것은 구분해야 합니다.

코드 근거 · 제목 중복 방지·구제 · 실제 텍스트 지도 · 경계 밖 제목 선택 · forest의 제목 경로 · 단일·그룹 조립 · 통합 순위 · 렌더·재배치

아래의 “재현됨”은 현재 로컬 코드의 함수를 직접 호출한 작은 사례에서 확인했다는 뜻입니다. 운영 DB에서 얼마나 자주 발생하는지까지 측정한 것은 아닙니다. 각 항목에서 “왜?”와 “반론”을 함께 읽으면, 이상해 보이는 모든 분기를 무조건 삭제하는 실수를 피할 수 있습니다.

좋은 수정은 반복문 수를 줄이는 작업이 아닙니다. 같은 조건을 두 번 확인하는 이유가 있는지, 끝낼 근거가 맞는지, 생략한 후보의 의미가 무엇인지를 먼저 따져야 합니다.

불필요해 보이는 계산은 어디에 남았나

• 정확 카테고리만 검색하는데 하위 Tier도 미리 만든다. 화면 searchOne은 항상 buildTiersFor를 전부 계산한 뒤 exactType이면 Tier 1만 남깁니다. N2가 많으면 결국 버릴 fallback 투영·성립 검사도 반복됩니다. exactType용 경로 또는 재사용 가능한 결과로 줄일 수 있습니다.
• 투영을 성립 검사와 Query Frame 생성 때 다시 한다. buildTiersFor가 투영해 검사한 구조를 버리고, buildQueryFrames가 같은 원본→도착 투영을 다시 만듭니다. 두 층의 책임을 유지하면서 변환 결과를 전달하는 방법을 검토할 수 있습니다.
• 페이지에서 검사한 행을 마지막에 다시 채점한다. 승인 수 확인용 평가와 최종 반환용 평가가 별도입니다. 현재는 예전 페이지 전체를 매 페이지 다시 채점하는 방식은 아닙니다. 최종 중복 평가를 줄이려면 새로운 matchedQueries가 추가돼 더 우선인 해석이 생길 수 있는 점을 함께 고려해야 합니다.
• contentLoss 가중치는 일반 검색 순위에서 효과가 없다. 해당 후보가 이미 하드 배제되기 때문입니다. 비용 API와 규약 정의를 위해 남긴 것은 이해할 수 있지만, 화면에서 값을 바꾸면 손실 허용이 달라질 것처럼 읽히면 혼란스럽습니다.

코드 주석도 현재 동작과 대조해야 합니다

documentSearch.ts 머리말의 “L3는 바로 평탄화”, search.ts 주변 문서의 “allocateSlots로 배분”, rank.ts의 “alternatives 우선순위”, summary-projection.ts의 “관계 종류·참가자까지 보존”은 현재 실행문과 맞지 않는 설명이 남은 사례입니다. 이 문서는 현재 실행문과 재현 결과로 설명하고, 규약 의도는 별도 근거로 표시합니다.

개선 순서 제안

1. 내용 누락·오류 전파·정렬 순환처럼 결과의 신뢰성을 깨는 F05·F07·F06을 먼저 다룬다.
2. 후보 발견과 종료의 의미를 맞춘다. F01·F02·F04와 스캔 소진 사유(F03)를 정리한다. 화면 사후 태그 필터가 결과를 비우고 코어를 보충시키지 않는 경로도 같이 본다.
3. 완성도와 품질를 나눠 본다. 누락된 조각(F09), 핵심 숫자·단위·조건, 카드별 분량 균형, 관계·순서, 남은 원문의 시각적 영향, 실제 겹침·잘림을 평가한다.
4. 합치기 때문에 길어진 문장이 itemOverflow·capOverflow·capChars에 이미 중복 반영되는지 보고 새 과밀도 벌점을 조정한다. 효과는 총점 하락보다 사용 가능한 결과 비율·원본 내용 보존·사람의 선택과 일치·검색 및 렌더 시간으로 검증한다.

코드 근거 · exactType 이전 전체 Tier 생성 · 성립용 투영 · Frame용 투영 · 최종 재채점 · 화면 사후 필터 · contentLoss 가중치 설명

“왜 이상한가?”에 답할 때는 입력 → 중간 상태 → 종료 조건 → 놓친 결과 순서로 말해 보세요. 단순히 “fallback이 너무 많다”보다 수정할 지점이 명확해집니다.

디버깅은 이 순서로 기록합니다

코드 근거 · 응답 메타 · 구조 탈락·해석 시도 · 호출 수와 시간 합

§2에서 Frame을 「내용과 디자인이 만나는 공통 표」로 배웠습니다. 그 Frame은 검색할 때 그 자리에서 만드는 것이 아니라 미리 만들어 테이블에 넣어 둔 것입니다. 검색이 읽는 색인이 바로 이 표입니다.

1. 본체는 frame 한 칸입니다 (jsonb)

검색과 대치가 실제로 쓰는 구조는 전부 이 jsonb 안에 있습니다. 나머지 47개 컬럼은 거기서 뽑아 둔 사본이거나 부가 정보입니다.

2. 검색 사전 필터용으로 펼친 컬럼

jsonb 안을 뒤지면 느리므로, §4의 사전 필터가 WHERE로 바로 거를 수 있게 밖으로 꺼내 둔 값들입니다. 원본은 어디까지나 frame이고 이 컬럼들은 사본입니다.

3. 식별과 중복 제거

frame_fingerprint · rlsc_fingerprint · unit_signature · design_object_uuid · template_idx · source. §9에서 본 같은 지문끼리 묶어 온전한 쪽을 대표로 세우는 처리가 frame_fingerprint를 씁니다.

4. 벌점 계산에 쓰는 부가 데이터

5. 버전은 다섯 축으로 따로 돕니다

「버전」이 하나가 아닙니다. 무엇이 낡았는지 말하려면 어느 축의 버전인지를 같이 말해야 합니다.

stale은 「이 행이 낡았다」 표시이고, built_at은 적재 시각입니다. provenance는 iis인지 rlsc-rule인지를 적습니다 — 분류는 IIS에서 받아도 Frame 자체는 규칙으로 만든 행이 있습니다.

6. 함정 둘

근거 규모·컬럼 구성·categories_from 전건 iis·ExtendableShapeItem 8,418개는 사용자가 2026-10-02에 2.5 전수를 직접 조회해 얻은 값이며 이 문서에서 DB로 재확인하지는 않았습니다. 전체 226,952행과 text_capacity:v2 225,382행(99.3%)·hardLimit은 저장소 문서(src/comp-frame/AGENTS.md)에서 교차 확인했습니다. categories_from·cap_source 타입은 packages/comp-frame-shared/src/types.ts에서 확인했습니다.

2026-09-13 로컬 체크아웃 기준입니다. 구현 저장소는 /Users/miridih/Documents/miricanvas-iui, 기준 커밋은 5d807e2dda8ff678fde227a436d7eea762e356bc입니다. 이 작업에서 인용한 packages/comp-frame와 src/comp-frame는 HEAD 대비 변경이 없음을 확인했습니다. 저장소의 다른 변경(Cargo.lock)은 건드리지 않았습니다. 원격을 새로 받아 “원격 최신”을 확인한 것은 아닙니다.

규약 저장소는 로컬 mordor-wiki 013fff131c99bc737ec4fd93ed38b3545675ba19입니다. comp-frame의 정본 fixture MANIFEST도 같은 커밋을 가리킵니다. 구현과 규약이 다르면 현재 실행 결과와 규약의 의도를 나눠 적었습니다. 코드 링크는 모두 이 고정 커밋을 가리킵니다.

작성 2026-09-08 · 기존 판 2026-09-12 · 전체 대조 및 수업자료 개정 2026-09-13. 과거 문서에 기록된 온라인 측정값을 이번 작업의 측정값으로 옮기지 않았습니다.