LLM-wiki Ingest flow

LLM-wiki Ingest flow: A.md / B.md 추적 예시

목표: A.md, B.md 두 문서를 ingest 했을 때 원본 chunk → LLM claim → wiki/claims.json → wiki/concepts/Matcher.md까지 어떤 ID로 연결되는지 한 번에 추적한다.

전제:

• 예시는 코드 규칙에 맞춘 추적용 샘플이다.
• LLM 응답 내용은 실행마다 달라질 수 있지만, ID 생성/보존/그룹핑 규칙은 코드 로직을 따른다.
• 아래 예시는 A.md에서는 summary=c1, Matcher concept=c2가 생성되고, B.md에서는 summary=c1, Tool concept=c2, Matcher concept=c3가 생성된 상황을 기준으로 한다.

0. 핵심 결론

flowchart LR
  A["A.md<br/>sourcePath=A.md<br/>sourceId=src:2d63174e212b2fdb"] --> AC["source chunk<br/>ordinal 0/1<br/>stableChunkId"]
  B["B.md<br/>sourcePath=B.md<br/>sourceId=src:b5038c9fd9be6c6f"] --> BC["source chunk<br/>ordinal 0/1<br/>stableChunkId"]

  AC --> AE["evidence<br/>src:2d63174e212b2fdb:e2<br/>A.md lines 2-2"]
  BC --> BE["evidence<br/>src:b5038c9fd9be6c6f:e3<br/>B.md lines 4-4"]

  AE --> AK["claimKey<br/>src:2d63174e212b2fdb:c2<br/>subject=Matcher"]
  BE --> BK["claimKey<br/>src:b5038c9fd9be6c6f:c3<br/>subject=Matcher"]

  AK --> REG["wiki/claims.json<br/>claim은 source-aware로 별도 보존"]
  BK --> REG

  REG --> GROUP["step8 concept grouping<br/>key=lowercase(trim(NFC(subject)))<br/>matcher"]
  GROUP --> WIKI["wiki/concepts/Matcher.md<br/>A.md 섹션 + B.md 섹션"]

핵심:

• claims.json에서는 A/B claim을 dedupe하지 않는다.
• claimKey는 sourcePath + claimId 기반이라 A.md의 Matcher와 B.md의 Matcher는 서로 다른 claim이다.
• concept wiki 단계에서만 subject 정규화값이 같은 claim들을 한 페이지에 모아 보여준다.

1. 예시 입력

A.md

# A
Matcher는 요청 조건을 평가해 대상 여부를 결정한다.
## Detail
Matcher는 라우팅 전에 입력 패턴을 검사한다.

B.md

# B
Tool 호출은 정책 검사를 먼저 통과해야 한다.
## Matcher
Matcher는 도구 호출 가능 여부를 판단하는 규칙 집합이다.

2. 단계별 전체 흐름

sequenceDiagram
  participant SRC as Source files
  participant S1 as step1 Discover/Classify
  participant S2 as step2 Parse/Chunk
  participant S4 as step4 LLM Generate
  participant S5 as step5 Validate
  participant S6 as step6 Backup/Write
  participant S7 as step7 Merge Claims
  participant S8 as step8 Sync Concept Wiki

  SRC->>S1: A.md, B.md scan
  S1->>S2: changed source documents
  S2->>S4: chunks + raw source
  S4->>S5: generated wiki page + SourceClaim[]
  S5->>S6: validated claims and markdown
  S6->>S7: claimUpdates + generated wiki page checkpoint
  S7->>S7: mergeSourceClaims(existing, updates, currentSourcePaths)
  S7->>S8: wiki/claims.json
  S8->>S8: concept claims grouped by normalized subject
  S8->>SRC: wiki/concepts/Matcher.md

주의: backend에는 step3 Queue Wiki work가 있지만 visualizer의 문서/실행 흐름에서는 내부 큐 단계라 핵심 설명에서 생략했다.

3. Step 1: source 식별

sourceId는 sourcePath만으로 만든다.

sourceId = "src:" + sha256(normalizedSourcePath).slice(0, 16)
claimKey = `${sourceId}:${claimId}`
evidenceId = `${sourceId}:e${n}`

file	sourcePath	sourceId
A.md	A.md	src:2d63174e212b2fdb
B.md	B.md	src:b5038c9fd9be6c6f

sourceHash는 파일 내용 sha256이다. 같은 path라도 내용이 바뀌면 sourceHash가 바뀌고, 변경 문서의 claim은 새 claim으로 교체된다.

file	sourceHash
A.md	f0cc8c7b6269d5a4094467448e032b8d05c10bc4bee9a5525b7102ecc40e7695
B.md	5fddc130a5be77b2b79abe79f96d37cfd925511c276e34b3a0b80883c2b970c0

4. Step 2: chunk 분할

Markdown chunk는 heading 기준으로 나뉜다. visualizer payload에는 ordinal, heading, lineStart, lineEnd가 노출된다.

DB에는 stableChunkId(sourcePath, sourceHash, ordinal, heading)가 저장된다.

flowchart TD
  A["A.md"] --> A0["chunk A#0<br/>heading=A<br/>lines 1-2<br/>stableChunkId=9ecb66ee7cd861b4580c3014"]
  A --> A1["chunk A#1<br/>heading=A > Detail<br/>lines 3-4<br/>stableChunkId=211e2203d68696ce4a1c8241"]

  B["B.md"] --> B0["chunk B#0<br/>heading=B<br/>lines 1-2<br/>stableChunkId=cdc1d32699ceb97f6c595e53"]
  B --> B1["chunk B#1<br/>heading=B > Matcher<br/>lines 3-4<br/>stableChunkId=81527e658148f0b10efd8066"]

sourcePath	visual chunk key	DB stableChunkId	heading	lines
A.md	A.md#0	9ecb66ee7cd861b4580c3014	A	1-2
A.md	A.md#1	211e2203d68696ce4a1c8241	A > Detail	3-4
B.md	B.md#0	cdc1d32699ceb97f6c595e53	B	1-2
B.md	B.md#1	81527e658148f0b10efd8066	B > Matcher	3-4

5. Step 4~5: LLM claim 생성과 검증

LLM은 원문에서 summary/concept/relationship을 만들고, 검증 단계에서 각 claim에 원문 evidence range가 붙는다.

예시에서는 A.md의 Matcher concept claim은 c2, B.md의 Matcher concept claim은 c3로 만들어졌다고 가정한다.

claimId는 문서별 local 순번이다. 같은 개념이라도 문서 안에서 몇 번째 summary/concept/relationship으로 만들어졌는지에 따라 c2, c3처럼 달라질 수 있다. evidence[0].lineStart-lineEnd도 원문 줄 번호라 우연히 같을 수도 있고, 아래처럼 다를 수도 있다.

flowchart LR
  A0["A.md chunk #0<br/>lines 1-2"] --> AE2["evidence<br/>id=src:2d63174e212b2fdb:e2<br/>sourcePath=A.md<br/>lines 2-2"]
  AE2 --> AC2["claim<br/>claimId=c2<br/>claimKey=src:2d63174e212b2fdb:c2<br/>kind=concept<br/>subject=Matcher"]

  B1["B.md chunk #1<br/>lines 3-4"] --> BE3["evidence<br/>id=src:b5038c9fd9be6c6f:e3<br/>sourcePath=B.md<br/>lines 4-4"]
  BE3 --> BC3["claim<br/>claimId=c3<br/>claimKey=src:b5038c9fd9be6c6f:c3<br/>kind=concept<br/>subject=Matcher"]

중요한 연결 규칙:

field	A.md Matcher claim	B.md Matcher claim
claimId	c2	c3
claimKey	src:2d63174e212b2fdb:c2	src:b5038c9fd9be6c6f:c3
kind	concept	concept
subject	Matcher	Matcher
sourcePath	A.md	B.md
sourceHash	A.md content hash	B.md content hash
evidenceIds[0]	src:2d63174e212b2fdb:e2	src:b5038c9fd9be6c6f:e3
evidence[0].sourcePath	A.md	B.md
evidence[0].lineStart-lineEnd	2-2	4-4

여기서 중요한 것은 claimId가 아니라 claimKey다. claimKey는 sourcePath 기반 sourceId를 포함하므로 source-aware claim identity가 된다.

6. Step 6: generated wiki page 저장

각 source 문서는 자기 소유 generated wiki page를 가진다.

flowchart LR
  A["A.md"] --> AW["wiki/generated/A.wiki.md<br/>sourcePath=A.md<br/>sourceHash=A hash"]
  B["B.md"] --> BW["wiki/generated/B.wiki.md<br/>sourcePath=B.md<br/>sourceHash=B hash"]

  AW --> AWC["wiki page chunks<br/>ordinal/heading/lines"]
  BW --> BWC["wiki page chunks<br/>ordinal/heading/lines"]

이 단계는 claim dedupe 단계가 아니다.

하는 일:

• 기존 generated wiki page 백업
• 새 markdown atomic write
• generated wiki page chunk를 DB에 upsert
• claimUpdates.push(...page.claims)로 이후 registry merge에 넘김

핵심 요약: A.wiki.md는 A.md를 LLM/검색/사람이 읽기 좋은 wiki markdown으로 재작성한 파일이다. claim 저장소는 아니며, 정규 claim 추적은 wiki/claims.json이 담당한다.

같은 LLM 응답에서 두 종류의 산출물이 함께 나온다고 보면 된다.

flowchart LR
  LLM["step4 LLM response<br/>A.md 분석 결과"] --> PAGE["page.markdown<br/>wiki/generated/A.wiki.md에 저장"]
  LLM --> CLAIMS["page.claims<br/>step7 wiki/claims.json에 병합"]

  PAGE --> INDEX["wiki_pages / wiki_chunks DB upsert"]
  CLAIMS --> REG["claimUpdates 배열"]

예시 wiki/generated/A.wiki.md 핵심 형태:

---
source_path: "A.md"
source_sha256: "f0cc8c7b6269d5a4094467448e032b8d05c10bc4bee9a5525b7102ecc40e7695"
aliases: ["Matcher"]
---
 
# A
 
Matcher는 요청 조건을 평가해 대상 여부를 결정한다.
 
## Matcher
 
Matcher는 요청 조건을 평가해 대상 여부를 결정하고, 라우팅 전에 입력 패턴을 검사한다.
 
## 원문 근거
 
- A.md:2-2 — Matcher는 요청 조건을 평가해 대상 여부를 결정한다.
- A.md:4-4 — Matcher는 라우팅 전에 입력 패턴을 검사한다.

이 파일의 역할:

• 검색/읽기용 wiki page다.
• sourcePath=A.md, sourceHash=A hash로 A.md에 소유된다.
• page markdown에서 다시 chunk가 만들어져 wiki_chunks에 저장된다.
• claim registry의 정규 원본은 아니다. 정규 claim 목록은 다음 단계의 wiki/claims.json이다.

7. Step 7: wiki/claims.json 통합

mergeSourceClaims(existing, updates, currentSourcePaths)가 실행된다.

위에서 아래로 읽으면 된다. 먼저 DB에 저장된 기존 source 목록과 현재 디스크 scan 결과를 합쳐 “현재 살아있는 source 목록”을 만든다. 그 다음 기존 wiki/claims.json과 이번 실행에서 새로 추출한 claim을 비교한다. 마지막으로 사라진 source의 claim은 제거하고, 이번에 다시 처리된 source의 claim은 새 claim으로 교체한다.

A.new는 A.md의 hash가 바뀌어 LLM이 다시 생성한 이번 실행의 새 claim을 뜻한다.

sequenceDiagram
  participant DB as DB 기존 source 목록
  participant Disk as 현재 디스크 scan
  participant Current as 현재 source 목록
  participant Prior as 기존 claims.json
  participant Updates as 이번 실행 claim
  participant Merge as claim 통합 로직
  participant Out as 최종 claims.json

  DB->>Current: 기존에 알던 path로 시작<br/>A.md, B.md, C.md
  Disk->>Current: 지금 발견된 path 반영<br/>A.md, B.md
  Current->>Current: 현재 source에 없는 path 제거<br/>C.md 제거
  Prior->>Merge: 기존 claim 전달<br/>A.old:c2, B.old:c3, C.old:c2
  Updates->>Merge: 이번에 새로 검증된 claim 전달<br/>A.new:c2, B.new:c3
  Current->>Merge: 현재 유효한 source 전달<br/>A.md, B.md
  Merge->>Merge: 사라진 source의 claim 제거<br/>C.old:c2 제거
  Merge->>Merge: 다시 처리된 source의 기존 claim 제거<br/>A.old:c2, B.old:c3 제거
  Merge->>Merge: 이번 실행 claim 추가<br/>A.new:c2, B.new:c3 추가
  Merge->>Out: 최종 registry 저장<br/>A.new:c2, B.new:c3

7-1. merge 시작 전 wiki/claims.json

아래는 이전 실행 결과가 남아 있는 상황이다.

{
  "version": 1,
  "claims": [
    {
      "claimKey": "src:2d63174e212b2fdb:c2",
      "subject": "Matcher",
      "sourcePath": "A.md",
      "statement": "OLD: A.md의 이전 Matcher 설명"
    },
    {
      "claimKey": "src:b5038c9fd9be6c6f:c3",
      "subject": "Matcher",
      "sourcePath": "B.md",
      "statement": "OLD: B.md의 이전 Matcher 설명"
    },
    {
      "claimKey": "src:removedsource0000:c2",
      "subject": "Removed Concept",
      "sourcePath": "C.md",
      "statement": "C.md는 이번 source set에 없음"
    }
  ]
}

7-2. 이번 실행 입력

{
  "currentSourcePaths": ["A.md", "B.md"],
  "updates": [
    {
      "claimKey": "src:2d63174e212b2fdb:c2",
      "subject": "Matcher",
      "sourcePath": "A.md",
      "statement": "NEW: A.md에서 새로 검증된 Matcher 설명"
    },
    {
      "claimKey": "src:b5038c9fd9be6c6f:c3",
      "subject": "Matcher",
      "sourcePath": "B.md",
      "statement": "NEW: B.md에서 새로 검증된 Matcher 설명"
    }
  ]
}

7-3. mergeSourceClaims 과정

// 1) currentSourcePaths에 없는 claim 제거
// - C.md claim 제거
 
// 2) 이번 updates에 포함된 source의 기존 claim 제거
// - A.md old claim 제거
// - B.md old claim 제거
 
// 3) updates claim 추가
// - A.md new claim 추가
// - B.md new claim 추가
 
// 4) claimKey 기준 Map으로 정리 후 정렬

7-4. merge 후 wiki/claims.json

예시 최종 wiki/claims.json 핵심 형태:

{
  "version": 1,
  "claims": [
    {
      "claimId": "c2",
      "claimKey": "src:2d63174e212b2fdb:c2",
      "kind": "concept",
      "subject": "Matcher",
      "statement": "Matcher는 요청 조건을 평가해 대상 여부를 결정한다.",
      "sourcePath": "A.md",
      "sourceHash": "f0cc8c7b6269d5a4094467448e032b8d05c10bc4bee9a5525b7102ecc40e7695",
      "evidenceIds": ["src:2d63174e212b2fdb:e2"],
      "evidence": [
        {
          "id": "src:2d63174e212b2fdb:e2",
          "sourcePath": "A.md",
          "sourceHash": "f0cc8c7b6269d5a4094467448e032b8d05c10bc4bee9a5525b7102ecc40e7695",
          "lineStart": 2,
          "lineEnd": 2,
          "quote": "Matcher는 요청 조건을 평가해 대상 여부를 결정한다."
        }
      ]
    },
    {
      "claimId": "c3",
      "claimKey": "src:b5038c9fd9be6c6f:c3",
      "kind": "concept",
      "subject": "Matcher",
      "statement": "Matcher는 도구 호출 가능 여부를 판단하는 규칙 집합이다.",
      "sourcePath": "B.md",
      "sourceHash": "5fddc130a5be77b2b79abe79f96d37cfd925511c276e34b3a0b80883c2b970c0",
      "evidenceIds": ["src:b5038c9fd9be6c6f:e3"],
      "evidence": [
        {
          "id": "src:b5038c9fd9be6c6f:e3",
          "sourcePath": "B.md",
          "sourceHash": "5fddc130a5be77b2b79abe79f96d37cfd925511c276e34b3a0b80883c2b970c0",
          "lineStart": 4,
          "lineEnd": 4,
          "quote": "Matcher는 도구 호출 가능 여부를 판단하는 규칙 집합이다."
        }
      ]
    }
  ]
}

시각적으로 보면:

flowchart LR
  AC2["A.md Matcher claim<br/>src:2d63174e212b2fdb:c2"] --> REG["wiki/claims.json"]
  BC3["B.md Matcher claim<br/>src:b5038c9fd9be6c6f:c3"] --> REG

  REG --> KEEP["두 claim 모두 보존<br/>dedupe 없음"]

8. Step 8: concept wiki 생성

이 단계에서 kind === "concept" claim만 모은다.

그룹 키:

conceptGroupKey = claim.subject.normalize("NFC").trim().toLocaleLowerCase()

예시에서는 두 claim 모두 subject=Matcher이므로 같은 그룹이 된다.

flowchart TD
  REG["wiki/claims.json"] --> FILTER["kind === concept"]
  FILTER --> ACLAIM["A.md<br/>subject=Matcher<br/>claimKey=src:2d63174e212b2fdb:c2"]
  FILTER --> BCLAIM["B.md<br/>subject=Matcher<br/>claimKey=src:b5038c9fd9be6c6f:c3"]

  ACLAIM --> GROUP["group key: matcher"]
  BCLAIM --> GROUP

  GROUP --> PAGE["wiki/concepts/Matcher.md"]
  PAGE --> SEC_A["section A.md<br/>A claim statement<br/>A evidence quote"]
  PAGE --> SEC_B["section B.md<br/>B claim statement<br/>B evidence quote"]

예시 wiki/concepts/Matcher.md 핵심 형태:

---
concept: "Matcher"
claim_keys: ["src:2d63174e212b2fdb:c2", "src:b5038c9fd9be6c6f:c3"]
sources: ["A.md", "B.md"]
generated_at: "..."
---
 
# Matcher
 
## A.md
 
Matcher는 요청 조건을 평가해 대상 여부를 결정한다.
 
> [!quote] A.md:2-2
> 
> Matcher는 요청 조건을 평가해 대상 여부를 결정한다.
 
## B.md
 
Matcher는 도구 호출 가능 여부를 판단하는 규칙 집합이다.
 
> [!quote] B.md:4-4
> 
> Matcher는 도구 호출 가능 여부를 판단하는 규칙 집합이다.

9. Dedupe가 아니라 concept projection인 이유

flowchart LR
  subgraph "dedupe라면"
    DA["A.md Matcher claim"] --> D["하나의 통합 claim"]
    DB["B.md Matcher claim"] --> D
  end

  subgraph "현재 llm-wiki"
    CA["A.md Matcher claim<br/>claimKey A:c2"] --> R["wiki/claims.json<br/>claim 2개 유지"]
    CB["B.md Matcher claim<br/>claimKey B:c3"] --> R
    R --> P["wiki/concepts/Matcher.md<br/>같은 페이지에 source별 섹션으로 표시"]
  end

구분	dedupe	현재 concept wiki
claim 개수	줄어든다	유지된다
claimKey	하나로 합쳐질 수 있다	source-aware key 그대로 유지
원본 추적	약해질 수 있다	sourcePath/sourceHash/evidence line 유지
목적	중복 제거	같은 개념의 claim들을 한 페이지에 모아 보기

10. ID 역추적 방법

wiki/concepts/Matcher.md에서 원본으로 돌아가는 경로:

flowchart RL
  PAGE["wiki/concepts/Matcher.md"] --> FK["frontmatter claim_keys"]
  FK --> CK["claimKey<br/>src:2d63174e212b2fdb:c2"]
  CK --> REG["wiki/claims.json에서 claim lookup"]
  REG --> SP["sourcePath=A.md"]
  REG --> SH["sourceHash=A hash"]
  REG --> EV["evidenceId=src:2d63174e212b2fdb:e2<br/>lineStart=2<br/>lineEnd=2"]
  EV --> SRC["A.md 원문 2번째 줄"]

체크리스트:

1. concept wiki frontmatter의 claim_keys를 확인한다.
2. 같은 claimKey를 wiki/claims.json에서 찾는다.
3. 해당 claim의 sourcePath, sourceHash, evidence[].lineStart-lineEnd를 확인한다.
4. sourcePath 원문 파일의 해당 line range를 보면 claim 근거로 돌아간다.
5. chunk 단위가 필요하면 같은 sourcePath에서 lineStart-lineEnd를 포함하는 source chunk를 찾는다.

11. 한 줄 모델

Source chunk는 원문 위치를 제공한다.
Claim은 source-aware key와 evidence로 원문에 고정된다.
claims.json은 claim을 dedupe하지 않고 source 단위로 교체/보존한다.
concept wiki는 같은 subject의 concept claim들을 한 페이지에 모아 보여주는 projection이다.

12. 코드 기준 위치

관심사	코드 기준
source chunk 구조	src/markdown.ts MarkdownChunk, chunkMarkdown()
DB source chunk id	src/index-store.ts stableChunkId(sourcePath, sourceHash, ordinal, heading)
sourceId / claimKey	src/claims.ts stableSourceId(), sourceClaimKey()
LLM 응답 → SourceClaim 생성	src/wiki-generator.ts buildSourceClaims()
source-owned generated wiki path	src/wiki-generator.ts wikiPagePath()
generated wiki 저장/checkpoint	src/indexer.ts enqueueWrite() / step6Payload()
wiki/claims.json 통합	src/indexer.ts mergeSourceClaims() 호출, src/claims.ts mergeSourceClaims()
concept wiki grouping/write	src/indexer.ts writeMergedConceptPages()

경로 표기 기준:

• 코드의 wikiPagePath("A.md") 결과는 generated/A.wiki.md이다.
• 문서에서는 runtime wiki root를 드러내기 위해 wiki/generated/A.wiki.md처럼 표기했다.
• concept page는 runtime wiki root 아래 wiki/concepts/Matcher.md로 이해하면 된다.

13. 현재 방식의 한계와 개선 방향

현재 방식은 source file 단위 교체다. 즉 A.md의 chunk 10개 중 1개만 바뀌어도 A.md 전체 hash가 바뀌고, A.md에서 나온 claim set 전체가 다시 생성·교체된다.

flowchart LR
  A["A.md<br/>chunk 10개"] --> C["chunk #4만 수정"]
  C --> H["A.md 전체 sourceHash 변경"]
  H --> LLM["A.md 전체를 LLM 재처리"]
  LLM --> OLD["기존 A.md claim 5개 제거"]
  LLM --> NEW["새 A.md claim set 전체 추가"]

예시:

실제 영향:
- chunk #4만 변경
- 기존 claim 5개 중 c2만 의미상 영향
 
현재 저장 결과:
- A.old:c1~c5 제거
- A.new:c1~c5 추가

한계:

• 작은 수정도 source 전체 claim churn을 만들 수 있다.
• LLM 재생성 때문에 영향 없는 claim의 문장, 순서, evidence가 흔들릴 수 있다.
• concept wiki와 검색 index/ranking도 불필요하게 변할 수 있다.

개선 방향:

source file 단위 교체
→ chunk hash 비교
→ 변경 chunk 찾기
→ 해당 chunk에 연결된 claim만 stale 처리
→ stale claim만 LLM patch
→ 영향받은 concept wiki만 재생성

핵심은 claim에 dependency를 명시하는 것이다.

{
  "claimKey": "src:2d63174e212b2fdb:c2",
  "sourcePath": "A.md",
  "dependsOnChunks": ["A.md#4"],
  "evidenceIds": ["src:2d63174e212b2fdb:e2"]
}

이렇게 되면 A.md#4만 바뀐 경우 c2만 재검증/수정하고, 나머지 claim은 그대로 보존할 수 있다.