kebab/tasks/phase-1-markdown-ingestion.md

phase, title, status, depends_on, source

phase	title	status	depends_on	source
P1	Markdown ingestion 파이프라인	planned	P0	kb_local_rust_report.md §8, §14, §17 Phase 1

P1 — Markdown ingestion 파이프라인

목표

Markdown 파일 -> RawAsset -> CanonicalDocument -> Chunk -> SQLite 흐름 완성. LLM/embedding 없이도 kb ingest / kb list docs / kb inspect doc <id> 동작.

산출 crate

crate	역할
kb-source-fs	local folder scan, checksum, 변경 감지. SourceConnector 구현
kb-parse-md	Markdown bytes → structured document. Extractor 구현
kb-normalize	parser output → CanonicalDocument
kb-chunk	block-aware chunking. Chunker 구현 (md-heading-v1)
kb-store-sqlite	metadata, document, chunk, job table. FTS table 은 P2 에서 활성화

kb-source-fs

• 입력: SourceScope { root: PathBuf, include: Vec<Glob>, exclude: Vec<Glob> }
• 동작: 재귀 walk → 각 파일 blake3 → RawAsset 목록.
• 변경 감지: (source_uri, checksum) 기준 신/구 비교. 동일 checksum 은 skip.
• watch 모드는 P1 범위 밖 (config 만 정의, 구현 후순위).

kb-parse-md

• parser 후보: pulldown-cmark 1차. GFM table/task list 필요해지면 comrak 검토 (§8).
• 보존 대상: YAML/TOML frontmatter, heading tree, paragraph, list, code block + lang tag, table, blockquote, link, image ref, line range.
• 출력: 중간 표현 (parser 고유). kb-normalize 가 canonical 로 변환.
• malformed markdown: panic 금지. 가능한 부분만 보존하고 Provenance 에 warning 기록.

kb-normalize

• 책임: parser 중간 표현 → CanonicalDocument.
• frontmatter → Metadata (id, title, aliases, tags, created_at, updated_at, source_type, trust_level, lang).
• block 트리 평탄화 + BlockId 부여 (heading path + 순번 기반 deterministic).
• SourceSpan 은 LineRange { start, end } 또는 ByteRange 둘 다 허용. Markdown 은 line range 1차.

kb-chunk (md-heading-v1)

우선순위 (§14):

1. heading boundary 우선
2. code block 중간 분할 금지
3. table 가능한 한 단일 chunk
4. 긴 section 은 paragraph 단위
5. heading_path 보존
6. source_spans 보존
7. chunker_version = "md-heading-v1" 기록

policy 기본값: target_tokens = 500, overlap_tokens = 80, respect_markdown_headings = true.

token 추정: tokenizer 미도입 단계라 byte / 문자 기반 근사 OK. 실제 tokenizer 는 P3 embedding 도입 시 교체.

kb-store-sqlite

스키마 (1차):

CREATE TABLE assets (
  asset_id TEXT PRIMARY KEY,
  source_uri TEXT NOT NULL,
  media_type TEXT NOT NULL,
  byte_len INTEGER NOT NULL,
  checksum TEXT NOT NULL,
  discovered_at TEXT NOT NULL
);

CREATE TABLE documents (
  doc_id TEXT PRIMARY KEY,
  asset_id TEXT NOT NULL REFERENCES assets(asset_id),
  title TEXT,
  lang TEXT,
  parser_version TEXT NOT NULL,
  doc_version INTEGER NOT NULL,
  metadata_json TEXT NOT NULL,
  provenance_json TEXT NOT NULL
);

CREATE TABLE blocks (
  block_id TEXT PRIMARY KEY,
  doc_id TEXT NOT NULL REFERENCES documents(doc_id),
  kind TEXT NOT NULL,
  heading_path TEXT NOT NULL,
  source_span_json TEXT NOT NULL,
  payload_json TEXT NOT NULL
);

CREATE TABLE chunks (
  chunk_id TEXT PRIMARY KEY,
  doc_id TEXT NOT NULL REFERENCES documents(doc_id),
  text TEXT NOT NULL,
  heading_path TEXT NOT NULL,
  source_spans_json TEXT NOT NULL,
  token_estimate INTEGER NOT NULL,
  chunker_version TEXT NOT NULL,
  block_ids_json TEXT NOT NULL
);

CREATE TABLE jobs (
  job_id TEXT PRIMARY KEY,
  kind TEXT NOT NULL,
  status TEXT NOT NULL,
  payload_json TEXT NOT NULL,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

• migration: refinery 또는 수동 SQL. 단순함이 우선.
• transaction: ingest 1건 = 1 transaction. 부분 실패 시 rollback.
• idempotent: 동일 doc_id 재수집은 UPSERT, version bump.

kb-app facade 확장

pub fn ingest(scope: SourceScope) -> anyhow::Result<IngestReport>;
pub fn list_docs(filter: DocFilter) -> anyhow::Result<Vec<DocSummary>>;
pub fn inspect_doc(id: &DocumentId) -> anyhow::Result<CanonicalDocument>;
pub fn inspect_chunk(id: &ChunkId) -> anyhow::Result<Chunk>;

IngestReport: { scanned, new, updated, skipped, errors }.

CLI

kb ingest <path> [--include <glob>] [--exclude <glob>]
kb list docs [--tag <t>]
kb inspect doc <doc_id>
kb inspect chunk <chunk_id>

테스트

• snapshot: fixtures/markdown/* → CanonicalDocument JSON 동결.
• snapshot: chunk 출력 (heading path / source span 포함) 동결.
• contract: 동일 입력 두 번 ingest → DB row 수 변화 없음 (idempotency).
• edge case: frontmatter only / nested headings / long paragraph / code block / table / image ref / relative link / malformed / 한영 혼합 (§18).

의존성 경계

kb-parse-md 금지: kb-store-*, kb-llm*, kb-rag, kb-tui, kb-desktop, embedding 호출. parser 는 순수 함수.

완료 조건

• kb ingest <path> 실행 후 SQLite 에 documents/blocks/chunks 채워짐
• kb list docs 정상 출력
• kb inspect doc <id> JSON 출력
• kb inspect chunk <id> JSON 출력 (heading path + source span 포함)
• 같은 폴더 재수집 시 중복 row 없음
• parser/chunker version 변경 시 재처리 대상 식별 가능
• fixture snapshot test 통과

리스크 / 주의

• chunker version 바꾸면 chunk_id 모두 변경. embedding 재생성 필요. version 막 올리지 말 것.
• frontmatter 파싱 실패 시 문서 전체 reject 금지. provenance 에 warning 만.
• line range 정확도가 P2 citation 품질을 좌우.