kebab/docs/components/normalize-chunk/README.md

Normalize + Chunk

Markdown 의 ParsedBlock 을 도메인 CanonicalDocument 로 lift 하고, 모든 미디어의 CanonicalDocument 를 검색 단위 Chunk 로 자른다.

구성 crate

Crate	역할
kebab-parse-md::normalize (모듈; 구 kebab-normalize, v0.19.0 에 kebab-parse-md 로 흡수)	ParsedBlock (markdown only) → CanonicalDocument lift. NFC + heading-path ordinal + provenance 합성 + title fallback chain (p9-fb-07).
kebab-chunk	CanonicalDocument → Vec<Chunk>. markdown 기본 md-heading-v2, PDF pdf-page-v1.2 — 둘 다 공유 crate::oversize (line→char 분할)로 예산 초과 청크를 잘라 모든 청크 ≤ max_chunk_tokens. md-heading-v1/pdf-page-v1.1 은 historical 변종으로 잔존.

구조

classDiagram
    class Normalize {
        <<kebab-parse-md::normalize>>
        build_canonical_document(asset, metadata, blocks, parser_version, warnings) CanonicalDocument
        derive_title(frontmatter, blocks, file_stem) String
        nfc(s) String
    }
    class Chunker {
        <<trait kebab-core>>
        chunker_version() ChunkerVersion
        policy_hash(policy) String
        chunk(doc, policy) Vec~Chunk~
    }
    class MdHeadingV1Chunker {
        VERSION = "md-heading-v1"
        BYTES_PER_TOKEN = 3
        POLICY_HASH_HEX_LEN = 16
    }
    class MdHeadingV2Chunker {
        VERSION = "md-heading-v2"
        max_chunk_tokens = 4000
        split_oversize_chunk(line→char)
    }
    class PdfPageV1Chunker {
        VERSION = "pdf-page-v1.2"
        max_chunk_tokens
        BYTES_PER_TOKEN = 3
        POLICY_HASH_HEX_LEN = 16
    }
    class ChunkPolicy {
        target_tokens
        overlap_tokens
        respect_markdown_headings
        chunker_version
    }
    Chunker <|.. MdHeadingV1Chunker
    Chunker <|.. MdHeadingV2Chunker
    Chunker <|.. PdfPageV1Chunker
    MdHeadingV2Chunker ..> ChunkPolicy
    PdfPageV1Chunker ..> ChunkPolicy

md-heading-v2 (기본, v0.30.0) 는 v1 과 모든 출력이 동일하되, 마지막에 token_estimate > max_chunk_tokens 인 청크만 줄(\n) 경계로 — 단일 거대 줄은 UTF-8 char 경계로 — 잘라 각 조각이 예산 이하가 되도록 한다. 분할 조각은 동일 block_ids 를 공유하므로 chunk_id 충돌을 막기 위해 id-input 해시에 #seg{i} 접미사를 붙이고(저장 policy_hash 는 bare), max_chunk_tokens 는 v2 의 policy_hash 에 fold 된다(공유 ChunkPolicy 미변경). 분할 조각의 source_spans 는 원 블록 범위를 그대로 보존(블록 단위 citation).

Data flow

flowchart TD
    Pblock["Vec~ParsedBlock~<br/>(kebab-parse-md)"]
    Asset["RawAsset<br/>(kebab-source-fs)"]
    Meta["Metadata<br/>(frontmatter)"]
    Pv["ParserVersion"]
    Norm["build_canonical_document<br/>NFC heading_path<br/>+ ordinal per (path, kind)<br/>+ derive_title fallback chain<br/>+ Provenance accumulator"]
    CDoc["CanonicalDocument<br/>(blocks + metadata + provenance)"]
    DirectCDoc["CanonicalDocument<br/>(kebab-parse-pdf / kebab-parse-image)"]
    MdC["MdHeadingV1Chunker<br/>(markdown + image)"]
    PdfC["PdfPageV1Chunker<br/>(PDF)"]
    Chunks["Vec~Chunk~"]
    Asset --> Norm
    Pblock --> Norm
    Meta --> Norm
    Pv --> Norm
    Norm --> CDoc
    CDoc --> MdC
    DirectCDoc --> MdC
    DirectCDoc --> PdfC
    MdC --> Chunks
    PdfC --> Chunks
    Chunks --> Store["kebab-store-* (다음 그룹)"]

주요 type / trait / 함수

Normalize (kebab-parse-md::normalize):

• build_canonical_document(asset: &RawAsset, metadata: Metadata, blocks: Vec<ParsedBlock>, parser_version: &ParserVersion, warnings: Vec<Warning>) -> Result<CanonicalDocument>.
  • doc_id = id_for_doc(workspace_path, asset_id, parser_version).
  • 모든 heading_path 에 NFC 정규화 적용 (NFD \u{1100}\u{1161} 와 NFC \u{AC00} = "가" 가 같은 block_id 로 hash 되도록).
  • ordinal = (heading_path, block_kind) 별 0-based, document order (§4.3).
  • title 은 metadata.user["title"] lift 후, 비어 있으면 derive_title(frontmatter_title, blocks, file_stem) chain.
  • lang 은 metadata.user["lang"] lift; non-string 이면 빈 Lang.
  • Provenance::events = Discovered (asset.discovered_at) + Parsed + Normalized + 각 warning 1개 + lift-stage warning (e.g. AudioRef pre-P8 drop).
• derive_title(frontmatter, &[Block], file_stem) -> String — fallback chain (p9-fb-07): frontmatter title → 첫 H1 → 첫 H2 → 첫 paragraph 80 chars → file stem → "untitled" sentinel.
• nfc(s: &str) -> String, to_posix(p: &Path) -> Result<WorkspacePath> — 재export from kebab-core.

Chunker trait (kebab-core):

• Chunker::chunker_version() -> ChunkerVersion.
• Chunker::policy_hash(&ChunkPolicy) -> String — blake3(canonical_json(policy))[..16]. v1 두 chunker 가 같은 recipe.
• Chunker::chunk(&CanonicalDocument, &ChunkPolicy) -> Result<Vec<Chunk>>.

MdHeadingV1Chunker (kebab-chunk):

• 우선순위 (§0/§14): heading 경계 → code/table 한 chunk → paragraph greedy + overlap → heading_path propagation.
• BYTES_PER_TOKEN = 3 (한국어 ≈ 3 b/tok 커버, 영어 ≈ 4 b/tok 는 over-estimate). 실제 tokenizer 도입 (P+) 까지 proxy.
• ImageRef / AudioRef 는 자체 chunk (text = alt/caption preview, token_estimate = 0).

PdfPageV1Chunker (kebab-chunk):

• 모든 chunk 가 single SourceSpan::Page { page, char_start, char_end } — 페이지 cross 금지 (citation locality).
• 페이지가 budget 초과 시 paragraph break (\n\n) → sentence end (./?/! + ws) → 강제 over-size 순서로 split.
• chunk_id 충돌 회피: §4.2 가 한 block_id 페어 → 한 chunk_id 가정인데 PDF 의 한 페이지 (= 한 block) 가 여러 chunk 로 split 됨. policy_hash slot 에 format!("{base}#c{char_start}") 변형 주입, Chunk.policy_hash 자체는 unmodified base 보존.

외부 의존

• crate dep:
  • kebab-parse-md::normalize (구 kebab-normalize crate, 이제 kebab-parse-md 모듈) → kebab-core, kebab-parse-md::types (ParsedBlock/ParsedPayload/Warning), unicode-normalization, time.
  • kebab-chunk → kebab-core, serde_json_canonicalizer, blake3. parser/store/embed 의존 금지.
• 외부 lib: unicode-normalization (NFC), blake3 (policy_hash), serde_json_canonicalizer (JCS), time (provenance timestamps).
• 외부 서비스: 없음.

핵심 결정

• Markdown 만 normalize 거침; PDF / Image 는 우회. 왜: Markdown 의 frontmatter / heading path 추적 + ordinal 부여가 normalize 의 본업. PDF 는 "페이지 = block", Image 는 "single block" 이라 IR 거치는 가치 없음. 결과: 두 path 가 chunker 단계에서 합류.

• heading_path NFC 정규화 (parsedBlock → canonical 시점). 왜: pulldown-cmark 가 NFC 안 함, serde_json_canonicalizer 도 NFC 안 함. 한국어 자모 분리/조합 두 표현이 다른 block_id hash 로 가면 idempotent re-ingest 가 깨짐. lift 시 NFC → on-disk CommonBlock.heading_path + ID input 동일 보장.

• ordinal rule = (heading_path, block_kind) 별 0-based, document order. 왜: 한 heading 아래 같은 종류의 블록 (paragraph 0/1/2, code 0/1) 만 ordinal 공유. 다른 heading 으로 가면 ordinal 리셋. 같은 heading 내 paragraph 추가/삭제가 다른 종류 ordinal 안 망가뜨림.

• derive_title fallback chain (5단계 + sentinel). 왜: spec literal 의 frontmatter-only title 정책이 실제 사용자 노트 (frontmatter 없이 H1 으로 시작) 와 충돌. 5단계: frontmatter → H1 → H2 → 첫 paragraph 80자 → file stem → "untitled". 각 단계 NFC, 빈 문자열 절대 반환 안 함. parser_version 을 pulldown-cmark-0.x → md-frontmatter-v2 bump 해서 기존 doc 자동 재처리.

• BYTES_PER_TOKEN = 3 (spec literal 의 4 거부). 왜: 한국어가 E5/M-BERT 에서 ≈ 3 bytes/token. 영어는 4 b/tok 라 3 으로 잡으면 over-estimate → 실제 tokenizer 가 봤을 때 budget 초과 안 함. 두 chunker (md/pdf) 가 같은 상수 써서 cross-chunker comparable. (HOTFIXES P7-2.)

• PDF chunk_id 충돌 회피 = policy_hash slot 에 #c{char_start} 변형. 왜: 한 페이지 (= 한 block) 가 여러 chunk 로 split 되면 §4.2 의 (doc_id, chunker_version, block_ids, policy_hash) tuple 가 동일 → 같은 chunk_id 충돌. chunker policy_hash 슬롯에만 변형 주입, Chunk.policy_hash 필드는 base 보존 ("어떤 policy 가 active 였는지" 답변 정확). §4.2 recipe 자체는 안 바꿈. (HOTFIXES P7-2.)

• chunker 가 store/embed 의존 금지. 왜: 순수 변환 함수. test 에서 CanonicalDocument 만 만들어서 chunker 호출 가능. Storage / embedding 부재가 chunker 단위 테스트 막지 않음.

관련 spec / HOTFIXES

• frozen 설계 §3.4 (Block / CanonicalDocument), §3.5 (Chunk), §3.6 (Provenance), §3.7b (ParsedBlock), §4.2 (ID recipe), §4.3 (ordinal), §0/§14 (chunking priority): docs/superpowers/specs/2026-04-27-kebab-final-form-design.md
• task specs: 삭제됨(2026-06-27 doc-reorg) — 설계는 frozen 계약, 동작은 tasks/HOTFIXES.md, 상세 git history.
• HOTFIXES (P7-2 BYTES_PER_TOKEN/=3, chunk_id 충돌 회피, p9-fb-07 title chain): tasks/HOTFIXES.md