kebab/docs/components/foundation/README.md

# Foundation

> 도메인 type, 설정, parser 공통 IR — workspace 의 모든 crate 가 의존하는 zero-dependency 토대.

## 구성 crate

| Crate | 역할 |
|-------|------|
| `kebab-core` | 도메인 type + ID recipe + trait. 다른 `kebab-*` crate 에 **의존 금지** (frozen 설계 §3, §4, §7). |
| `kebab-parse-types` | parser intermediate (`ParsedBlock`) — `kebab-core` 만 의존. parser library (`pulldown-cmark`, `lopdf` 등) 의존 금지 (§3.7b). |
| `kebab-config` | `Config` 스키마 + XDG path resolver. `defaults → file → env (KEBAB_*)` 3 layer (§6). |

## 구조

```mermaid
classDiagram
    class IDs {
        AssetId
        DocumentId
        BlockId
        ChunkId
        EmbeddingId
        IndexId
    }
    class Versions {
        ParserVersion
        ChunkerVersion
        EmbeddingVersion
        IndexVersion
        PromptTemplateVersion
    }
    class DomainTypes {
        RawAsset
        CanonicalDocument
        Block enum
        Chunk
        Citation
        SearchHit
        Answer
        Turn
    }
    class Traits {
        SourceConnector
        Extractor
        Chunker
        Embedder
        Retriever
        LanguageModel
        DocumentStore
        VectorStore
        JobRepo
        ChatSessionRepo
    }
    class ParsedIR {
        ParsedBlock
        ParsedBlockKind
        ParsedPayload
        Warning
    }
    class Config {
        workspace
        storage
        indexing
        chunking
        models
        search
        rag
        image
        ui
    }
    DomainTypes ..> IDs : carries
    DomainTypes ..> Versions : stamps
    Traits ..> DomainTypes : produce/consume
    ParsedIR ..> DomainTypes : Inline + SourceSpan
    Config ..> Versions : seeds (parser/chunker/embedding)
```

## Data flow — ID recipe

모든 ID 는 동일한 recipe (§4.2). tuple 의 (kind, key fields) → 정렬된 canonical JSON → `blake3` → hex 앞 32자.

```mermaid
flowchart LR
    Tuple["tuple<br/>(kind, key fields)"]
    JSON["canonical JSON<br/>(JCS, alphabetical key order)"]
    Hash["blake3 32 byte digest"]
    Hex["hex string 앞 32자"]
    ID["AssetId/DocumentId/<br/>BlockId/ChunkId/<br/>EmbeddingId/IndexId"]
    Tuple --> JSON --> Hash --> Hex --> ID
```

핵심 invariant: 같은 tuple → 같은 ID, 무한 idempotent. `id_for_*` helper 가 tuple 조립까지 캡슐화 — caller 는 입력만 넘김.

## 주요 type / trait / 함수

**IDs / 버전** (`ids.rs`, `versions.rs`):
- `AssetId(String)` — 32 hex, `blake3` content addressed.
- `id_for_doc(&WorkspacePath, &AssetId, &ParserVersion) -> DocumentId` — `parser_version` 갈리면 doc 도 갈림 (cascade).
- `id_for_chunk(&DocumentId, &ChunkerVersion, &[BlockId], policy_hash: &str) -> ChunkId` — `policy_hash` 가 chunk-policy 변화 capture.
- `id_for_embedding(&ChunkId, &EmbeddingModelId, &EmbeddingVersion, dims: usize) -> EmbeddingId`.

**도메인 type** (`document.rs`, `chunk.rs`, `citation.rs`, `answer.rs`):
- `Block` (enum) — `Heading`, `Paragraph`, `Code`, `List`, `Table`, `ImageRef`, `AudioRef`, `Quote`. `CanonicalDocument` 가 보유.
- `Citation` — URI fragment (`path#L12-L34` / `path#p=12` / `path#xywh=…`).
- `Answer { text, citations, refusal_reason: Option<RefusalReason>, conversation_id, turn_index, ... }` — multi-turn 메타 (p9-fb-15).
- `Turn { question, answer, ... }` — chat history.

**Trait** (`traits.rs`) — pipeline contract. 자세한 내용은 각 그룹 페이지:
- `Extractor` (→ Parse), `Chunker` (→ Normalize+Chunk), `Embedder` (→ Embed), `Retriever` (→ Search), `LanguageModel` (→ LLM), `DocumentStore` / `VectorStore` (→ Store), `ChatSessionRepo` (→ Store, p9-fb-17).

**ParsedBlock IR** (`kebab-parse-types`):
- `ParsedBlock { kind, heading_path, source_span, payload: ParsedPayload }` — 모든 parser 의 공통 출력.
- `Warning { kind: WarningKind, note }` — `MalformedFrontmatter` / `MalformedTable` / `EncodingFallback` / `ExtractFailed`.

**Config** (`kebab-config`):
- `Config::load(Option<&Path>) -> anyhow::Result<Self>` — 3 layer merge.
- `Config::resolve_workspace_root(&self) -> PathBuf` — relative `workspace.root` 을 config 파일 디렉토리 기준으로 해석 (p9-fb-05).
- `Config::xdg_config_path() / xdg_data_dir() / xdg_cache_dir() / xdg_state_dir()` — XDG 표준 디렉토리.
- env override 키 패턴: `KEBAB_<SECTION>_<KEY>` (예: `KEBAB_RAG_SCORE_GATE`, `KEBAB_SEARCH_DEFAULT_K`). 알려지지 않은 키는 silently ignore.

## 외부 의존

- `kebab-core`: `serde` + `serde_json` + `serde_json_canonicalizer` (JCS) + `blake3` + `time` + `uuid`. parser/store/llm crate 의존 **금지**.
- `kebab-parse-types`: `kebab-core` + `serde` 만.
- `kebab-config`: `kebab-core` + `serde` + `toml` + `dirs` + `tracing`.

## 핵심 결정

- **ID recipe = tuple → JCS → blake3[..32]**.
  **왜**: 동일 tuple → 항상 동일 ID. JCS (RFC 8785) 가 key 정렬을 강제해서 struct field 순서가 hash 에 영향 안 미침. 32 hex (128 bit) 가 충돌 무시할 만큼 작고 SQLite TEXT PK 로 다루기 좋음.
  **검증**: `tests::id_for_*_pinned` 가 외부 도구 (`b3sum`) 로 hand-computed 한 hex 와 매칭 — JCS / hash pipeline 의 회귀를 즉시 잡음.

- **`parser_version` / `chunker_version` / `embedding_version` / `index_version` / `prompt_template_version` 5 cascade**.
  **왜**: 각 단계 산출물의 ID 가 상위 version 을 tuple 에 포함 → version bump 시 downstream record 가 자동으로 무효화 (frozen 설계 §9). eval runner 가 5 개 모두 `eval_runs.config_snapshot_json` 으로 snapshot.

- **`Config.source_dir` (`#[serde(skip)]` + `pub(crate)`)**.
  **왜**: `--config /tmp/cfg.toml` + `workspace.root = "kb"` 가 `cwd` 무관하게 `/tmp/kb` 로 해석되어야 함. p9-fb-05 의 path policy. `from_file` / `load` 만 stamp 하므로 외부 호출자가 망가뜨릴 수 없음.

- **`#[serde(default)]` 의 점진적 신설**.
  **왜**: pre-P6 config 파일 (`[image]` 섹션 없음) + pre-p9-fb-14 config (`[ui]` 섹션 없음) 가 그대로 load 가능. 사용자가 `kebab init` 매번 재실행 안 해도 됨.

- **env override 미지의 키 silent ignore**.
  **왜**: `KEBAB_NOPE_FOO=garbage` 같은 환경변수가 startup 을 죽이면 안 됨. whitelist 기반 명시 매칭 — grep 으로 모든 매핑 한 눈에 확인 가능.

## 관련 spec / HOTFIXES

- frozen 설계 §3 (도메인 type) / §4 (ID) / §6 (Config) / §7 (trait) / §9 (cascade): [`docs/superpowers/specs/2026-04-27-kebab-final-form-design.md`](../../superpowers/specs/2026-04-27-kebab-final-form-design.md)
- p9-fb-05 (`workspace.root` path policy): [`tasks/p9/p9-fb-05-config-path-policy.md`](../../../tasks/p9/p9-fb-05-config-path-policy.md)
- p9-fb-15 (RAG multi-turn — `Turn`, `Answer.conversation_id`/`turn_index`): [`tasks/p9/p9-fb-15-rag-multi-turn-core.md`](../../../tasks/p9/p9-fb-15-rag-multi-turn-core.md)
- p9-fb-17 (chat session storage — `ChatSessionRow`, `ChatTurnRow`, `ChatSessionRepo`): [`tasks/p9/p9-fb-17-chat-session-storage.md`](../../../tasks/p9/p9-fb-17-chat-session-storage.md)
- HOTFIXES dated 로그 (P3-5/P4-3 `--config` 누락, P6-3 `GenerateRequest.images` 신설 등): [`tasks/HOTFIXES.md`](../../../tasks/HOTFIXES.md)