claude-memory-layer 1.0.11 → 1.0.13

package/memory/specs/evidence-aligner-v2/2026-02-25.md

@@ -0,0 +1,1028 @@
+
+## 2026-02-25T12:31:26.308Z | 0639bac9-22ca-42c0-9c40-36d77d38896f
+- type: session_summary
+- session: import:organized
+# Evidence Aligner V2 Context
+
+> **Version**: 2.0.0
+> **Created**: 2026-01-31
+
+## 1. 배경
+
+### 1.1 LLM 오프셋 계산의 문제
+
+LLM에게 텍스트 내 정확한 문자 위치(spanStart/spanEnd)를 계산하도록 요청하면:
+
+```json
+// LLM 출력 (문제 있음)
+{
+  "quote": "JSONB 제거",
+  "spanStart": 142,
+  "spanEnd": 150
+}
+```
+
+**실제 문제**:
+1. LLM은 토큰 기반으로 동작하여 문자 단위 계산이 부정확
+2. 멀티바이트 문자(한글 등)에서 오프셋 계산 오류 빈번
+3. 원문을 보지 않고 추측하는 경우 발생
+
+### 1.2 Quote-only 방식의 장점
+
+```json
+// LLM 출력 (개선)
+{
+  "messageIndex": 3,
+  "quote": "DuckDB의 JSONB를 JSON으로 변경"
+}
+```
+
+**장점**:
+1. LLM은 인용만 담당 (잘하는 것)
+2. 정확한 위치 계산은 시스템이 담당
+3. 검증 가능: quote가 원문에 없으면 즉시 탐지
+
+## 2. Memo.txt 참고 사항
+
+### 2.1 핵심 원칙 (섹션 2.4)
+
+> **4. EvidenceSpan은 파이프라인이 확정**
+> - LLM에게 spanStart/spanEnd 요구 금지
+> - LLM은 quote만 제공 → aligner가 원문에서 찾아 span을 계산
+
+### 2.2 Extractor 출력 스키마 (섹션 6.1)
+
+```json
+{
+  "entries":[
+    {
+      "entryId":"ent_...",
+      "type":"fact",
+      "title":"DuckDB JSONB 제거",
+      "evidence":[{"messageIndex":3,"quote":"content JSONB → JSON"}]
+    }
+  ]
+}
+```
+
+### 2.3 정렬 알고리즘 (섹션 6.2)
+
+1. **exact substring match**
+2. **normalize(공백/개행 collapse) 후 fuzzy match (최소 0.85 이상)** — optional
+3. 실패 시 `evidenceAligned=false`로 표시하고, 해당 엔트리는 **Verified 승격 금지**
+
+## 3. Idris2 영감 적용
+
+### 3.1 Proof-Carrying Data
+
+**Idris2 개념**:
+```idris
+-- 주장과 증거가 타입 수준에서 연결
+data ProvenClaim : Type where
+  MkClaim : (claim : String) ->
+            (evidence : Span) ->
+            (proof : InSource evidence) ->  -- 증거가 원문에 있다는 증명
+            ProvenClaim
+```
+
+**TypeScript 적용**:
+```typescript
+// 정렬 성공한 증거만 특정 타입으로
+type AlignedEvidence = {
+  quote: string;
+  span: { start: number; end: number };
+  matchMethod: 'exact' | 'normalized' | 'fuzzy';
+  confidence: number;  // matchMethod에 따라 범위 제한
+};
+
+// 정렬 실패는 별도 타입
+type FailedEvidence = {
+  quote: string;
+  failureReason: 'not_found' | 'below_threshold' | 'ambiguous';
+};
+
+// Union으로 구분
+type Evidence = AlignedEvidence | FailedEvidence;
+```
+
+### 3.2 Confidence 불변식
+
+```typescript
+// Zod refinement로 불변식 검증
+const AlignedEvidenceSchema = z.object({
+  matchMethod: z.enum(['exact', 'normalized', 'fuzzy']),
+  confidence: z.number()
+}).refine(data => {
+  switch (data.matchMethod) {
+    case 'exact':
+      return data.confidence === 1.0;
+    case 'normalized':
+      return data.confidence >= 0.95 && data.confidence < 1.0;
+    case 'fuzzy':
+      return data.confidence >= 0.85 && data.confidence < 0.95;
+  }
+}, { message: 'Confidence must match method' });
+```
+
+## 4. 기존 코드와의 관계
+
+### 4.1 현재 evidence-aligner.ts
+
+```typescript
+// 현재 구현 (src/core/evidence-aligner.ts)
+export class EvidenceAligner {
+  align(claims: string[], sourceContent: string): AlignmentResult {
+    for (const claim of claims) {
+      const exactSpan = this.findExactMatch(claim, sourceContent);
+      if (exactSpan) {
+        spans.push(exactSpan);
+        continue;
+      }
+      missingClaims.push(claim);
+    }
+  }
+
+  private findExactMatch(claim: string, source: string): EvidenceSpan | null {
+    const index = source.indexOf(claim);
+    if (index === -1) return null;
+    return { start: index, end: index + claim.length, ... };
+  }
+}
+```
+
+### 4.2 V2 확장 포인트
+
+| 기존 | V2 확장 |
+|-----|---------|
+| claims: string[] | extractedJson with messageIndex |
+| sourceContent: string | sessionMessages: string[] |
+| exactMatch only | exact → normalized → fuzzy fallback |
+| 반환: spans + missingClaims | 반환: AlignResult with details |
+
+### 4.3 하위 호환성
+
+```typescript
+// 기존 API 유지
+class EvidenceAlignerV2 extends EvidenceAligner {
+  // 기존 메서드 오버라이드
+  align(claims: string[], sourceContent: string): AlignmentResult {
+    // V2 로직으로 처리 후 기존 형식으로 변환
+    const v2Result = this.alignV2([sourceContent], {
+      evidence: claims.map((c, i) => ({ quote: c, messageIndex: 0 }))
+    });
+    return this.convertToV1Result(v2Result);
+  }
+
+  // 새 API
+  alignV2(sessionMessages: string[], extractedJson: ExtractedData): AlignResult;
+}
+```
+
+## 5. 정규화 전략
+
+### 5.1 공백 정규화
+
+```typescript
+function normalizeWhitespace(text: string): string {
+  return text
+    .replace(/[\t\r]/g, ' ')      // 탭, CR → 공백
+    .replace(/\n+/g, ' ')          // 개행 → 공백
+    .replace(/ +/g, ' ')           // 연속 공백 → 단일 공백
+    .trim();
+}
+```
+
+### 5.2 위치 역추적 문제
+
+정규화 후 매칭 시, 원본 위치를 찾아야 함:
+
+```typescript
+// 원본: "Hello   World\n\nTest"
+// 정규화: "Hello World Test"
+// 매칭: "World Test" at 6-16 (정규화)
+// 역추적: 원본에서 "World\n\nTest" 찾기
+
+function mapToOriginal(
+  original: string,
+  normalized: string,
+  normalizedStart: number,
+  normalizedEnd: number
+): { start: number; end: number } {
+  // 각 문자 위치 매핑 테이블 생성
+  const posMap = buildPositionMap(original, normalized);
+  return {
+    start: posMap.normalizedToOriginal.get(normalizedStart)!,
+    end: posMap.normalizedToOriginal.get(normalizedEnd - 1)! + 1
+  };
+}
+```
+
+### 5.3 유니코드 고려
+
+```typescript
+// 한글, 이모지 등 멀티바이트 문자 처리
+function normalizeUnicode(text: string): string {
+  return text
+    .normalize('NFKC')             // 유니코드 정규화
+    .replace(/\p{Zs}/gu, ' ')      // 모든 공백 문자 → 일반 공백
+    .replace(/\p{Cf}/gu, '');      // 보이지 않는 포맷 문자 제거
+}
+```
+
+## 6. Fuzzy Matching 전략
+
+### 6.1 Levenshtein 거리
+
+```typescript
+function levenshteinDistance(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  const dp: number[][] = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,      // 삭제
+        dp[i][j - 1] + 1,      // 삽입
+        dp[i - 1][j - 1] + cost // 대체
+      );
+    }
+  }
+  return dp[m][n];
+}
+
+function similarity(a: string, b: string): number {
+  const dist = levenshteinDistance(a, b);
+  const maxLen = Math.max(a.length, b.length);
+  return 1 - dist / maxLen;
+}
+```
+
+### 6.2 슬라이딩 윈도우 최적화
+
+```typescript
+function findBestMatch(
+  quote: string,
+  source: string,
+  threshold: number
+): { start: number; end: number; score: number } | null {
+  const quoteLen = quote.length;
+  const windowSizes = [quoteLen, quoteLen * 1.1, quoteLen * 1.2];  // 다양한 윈도우
+
+  let best: { start: number; end: number; score: number } | null = null;
+
+  for (const windowSize of windowSizes) {
+    const size = Math.ceil(windowSize);
+    for (let i = 0; i <= source.length - size; i++) {
+      const window = source.slice(i, i + size);
+      const score = similarity(quote, window);
+
+      if (score >= threshold && (!best || score > best.score)) {
+        best = { start: i, end: i + size, score };
+      }
+    }
+  }
+
+  return best;
+}
+```
+
+## 7. 에러 케이스 처리
+
+### 7.1 messageIndex 범위 초과
+
+```typescript
+function validateEvidence(evidence: ExtractedEvidence, messageCount: number): ValidationResult {
+  if (evidence.messageIndex >= messageCount) {
+    return {
+      valid: false,
+      error: `messageIndex ${evidence.messageIndex} out of range (max: ${messageCount - 1})`
+    };
+  }
+  return { valid: true };
+}
+```
+
+### 7.2 빈 quote
+
+```typescript
+if (!evidence.quote || evidence.quote.trim().length === 0) {
+  return {
+    aligned: false,
+    failureReason: 'empty_quote'
+  };
+}
+```
+
+### 7.3 애매한 매칭 (여러 위치에서 발견)
+
+```typescript
+function handleAmbiguousMatch(
+  quote: string,
+  source: string
+): AlignResult {
+  const matches = findAllMatches(quote, source);
+
+  if (matches.length > 1) {
+    // 첫 번째 매칭 사용, 단 애매함 표시
+    return {
+      ...matches[0],
+      meta: { ambiguous: true, alternativeCount: matches.length - 1 }
+    };
+  }
+  return matches[0];
+}
+```
+
+## 8. 성능 고려사항
+
+### 8.1 캐싱
+
+```typescript
+// 정규화 결과 캐싱 (동일 소스 반복 사용 시)
+const normalizeCache = new Map<string, { normalized: string; posMap: PositionMap }>();
+
+function getCachedNormalized(source: string): { normalized: string; posMap: PositionMap } {
+  if (!normalizeCache.has(source)) {
+    const normalized = normalize(source);
+    const posMap = buildPositionMap(source, normalized);
+    normalizeCache.set(source, { normalized, posMap });
+  }
+  return normalizeCache.get(source)!;
+}
+```
+
+### 8.2 조기 종료
+
+```typescript
+// Exact match 성공 시 fuzzy 시도 안 함
+function align(quote: string, source: string): AlignedSpan | null {
+  // Step 1: Exact (가장 빠름)
+  const exact = exactMatch(quote, source);
+  if (exact) return exact;
+
+  // Step 2: Normalized (중간)
+  const normalized = normalizedMatch(quote, source);
+  if (normalized) return normalized;
+
+  // Step 3: Fuzzy (가장 느림, 필요할 때만)
+  return fuzzyMatch(quote, source, 0.85);
+}
+```
+
+### 8.3 긴 텍스트 처리
+
+```typescript
+// 매우 긴 소스의 경우 분할 처리
+const CHUNK_SIZE = 10000;
+
+function alignLongSource(quote: string, source: string): AlignedSpan | null {
+  if (source.length <= CHUNK_SIZE) {
+    return align(quote, source);
+  }
+
+  // 청크 단위로 검색 (오버랩 적용)
+  const overlap = quote.length * 2;
+  for (let i = 0; i < source.length; i += CHUNK_SIZE - overlap) {
+    const chunk = source.slice(i, i + CHUNK_SIZE);
+    const result = align(quote, chunk);
+    if (result) {
+      return { ...result, start: result.start + i, end: result.end + i };
+    }
+  }
+  return null;
+}
+```
+
+## 9. 참고 자료
+
+- **Memo.txt**: 섹션 6 - Evidence Align 구현 지시
+- **현재 구현**: `src/core/evidence-aligner.ts`
+- **타입 정의**: `src/core/types.ts` - EvidenceSpan
+- **AXIOMMIND**: Principle 4 - 증거 범위 확정
+
+## 2026-02-25T12:31:26.316Z | 4cbc96d4-1d7b-44d6-b9b2-6ef35d5c91d2
+- type: session_summary
+- session: import:organized
+# Evidence Aligner V2 Implementation Plan
+
+> **Version**: 2.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## Phase 1: Extractor 수정 (P0)
+
+### 1.1 프롬프트 변경
+
+**작업 항목**:
+- [ ] LLM 프롬프트에서 spanStart/spanEnd 요구 제거
+- [ ] quote 필드 필수로 변경
+- [ ] quote 길이 가이드라인 추가 (30~200자)
+
+**프롬프트 예시**:
+```
+각 entry에 대해 evidence를 제공하세요.
+- messageIndex: 증거가 있는 메시지 인덱스 (0-based)
+- quote: 원문에서 발췌한 텍스트 (30~200자)
+
+중요: spanStart/spanEnd는 제공하지 마세요. 시스템이 자동으로 계산합니다.
+```
+
+### 1.2 파서 수정
+
+**파일**: `src/core/extractor.ts` (가정)
+
+**작업 항목**:
+- [ ] 출력 스키마에서 spanStart/spanEnd 제거
+- [ ] quote 필수 검증 추가
+- [ ] messageIndex 범위 검증
+
+## Phase 2: Aligner 핵심 구현 (P0)
+
+### 2.1 타입 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+// 추가할 타입들
+export const AlignMethodSchema = z.enum(['exact', 'normalized', 'fuzzy', 'none']);
+
+export const AlignedEvidenceSchema = z.object({
+  messageIndex: z.number().int().nonnegative(),
+  quote: z.string(),
+  quoteHash: z.string(),
+  spanStart: z.number().int().nonnegative(),
+  spanEnd: z.number().int().positive(),
+  confidence: z.number().min(0).max(1),
+  matchMethod: AlignMethodSchema
+});
+```
+
+**작업 항목**:
+- [ ] AlignMethod 타입 추가
+- [ ] AlignedEvidence 스키마 추가
+- [ ] AlignResult 스키마 추가
+- [ ] EvidenceAlignedEvent 타입 추가
+
+### 2.2 Aligner 클래스 확장
+
+**파일**: `src/core/evidence-aligner.ts` 수정
+
+```typescript
+export class EvidenceAlignerV2 {
+  constructor(private config: AlignerConfig);
+
+  // 메인 정렬 함수
+  async align(
+    sessionMessages: string[],
+    extractedJson: ExtractedData
+  ): Promise<AlignResult>;
+
+  // 단계별 매칭
+  private exactMatch(quote: string, source: string): AlignedSpan | null;
+  private normalizedMatch(quote: string, source: string): AlignedSpan | null;
+  private fuzzyMatch(quote: string, source: string, threshold: number): AlignedSpan | null;
+
+  // 헬퍼
+  private normalize(text: string): string;
+  private levenshteinSimilarity(a: string, b: string): number;
+  private mapToOriginal(source: string, normalized: string, start: number, length: number): Span;
+}
+```
+
+**작업 항목**:
+- [ ] exactMatch 메서드 구현
+- [ ] normalize 함수 구현
+- [ ] normalizedMatch 메서드 구현 (위치 역추적 포함)
+- [ ] levenshteinSimilarity 함수 구현
+- [ ] fuzzyMatch 메서드 구현 (슬라이딩 윈도우)
+- [ ] align 메인 함수 구현 (3단계 폴백)
+
+### 2.3 설정
+
+```typescript
+interface AlignerConfig {
+  fuzzyThreshold: number;        // default: 0.85
+  maxQuoteLength: number;        // default: 500
+  enableFuzzy: boolean;          // default: true
+}
+```
+
+## Phase 3: 이벤트 연동 (P0)
+
+### 3.1 이벤트 발행
+
+**파일**: `src/core/event-store.ts` 수정
+
+**작업 항목**:
+- [ ] 'evidence_aligned' 이벤트 타입 추가
+- [ ] payload 스키마 정의
+
+### 3.2 Orchestrator 연동
+
+**파일**: 파이프라인 연동 (graduation.ts 또는 신규)
+
+```typescript
+async function processSession(session: Session): Promise<void> {
+  // 1. session_ingested 이벤트
+  const ingestEvent = await eventStore.append({ eventType: 'session_ingested', ... });
+
+  // 2. LLM 추출
+  const extracted = await extractor.extract(session);
+  await eventStore.append({ eventType: 'memory_extracted', ... });
+
+  // 3. Evidence 정렬 (V2)
+  const alignResult = await aligner.align(session.messages, extracted);
+  await eventStore.append({
+    eventType: 'evidence_aligned',
+    content: JSON.stringify({
+      source_event_id: ingestEvent.eventId,
+      aligned_count: alignResult.alignedEvidence.length,
+      failed_count: alignResult.failedQuotes.length,
+      evidence: alignResult.alignedEvidence,
+      failed_quotes: alignResult.failedQuotes
+    })
+  });
+
+  // 4. Entry 저장 (alignResult 반영)
+  for (const entry of extracted.entries) {
+    const entryEvidence = alignResult.alignedEvidence.filter(
+      e => e.entryId === entry.entryId
+    );
+    entry.evidenceAligned = entryEvidence.every(e => e.matchMethod !== 'none');
+    // ...
+  }
+}
+```
+
+**작업 항목**:
+- [ ] process_session 흐름에 aligner 삽입
+- [ ] evidence_aligned 이벤트 발행
+- [ ] entry에 evidenceAligned 플래그 설정
+
+## Phase 4: 승격 정책 적용 (P0)
+
+### 4.1 Graduation 조건 수정
+
+**파일**: `src/core/graduation.ts` 수정
+
+```typescript
+async function promoteToVerified(entry: Entry): Promise<PromotionResult> {
+  // Evidence 정렬 확인
+  if (!entry.evidenceAligned) {
+    return {
+      success: false,
+      reason: 'Evidence alignment failed. Cannot promote to Verified.'
+    };
+  }
+
+  // 기타 조건 확인...
+}
+```
+
+**작업 항목**:
+- [ ] candidate → verified 승격 조건에 evidenceAligned 추가
+- [ ] 실패 시 명확한 reason 제공
+
+### 4.2 메타데이터 기록
+
+**작업 항목**:
+- [ ] entry.meta.promotionBlocked 플래그
+- [ ] entry.meta.promotionBlockReason 기록
+- [ ] entry.meta.failedQuotes 저장 (디버깅용)
+
+## Phase 5: 유틸리티 및 테스트 (P1)
+
+### 5.1 Levenshtein 구현
+
+**파일**: `src/core/string-utils.ts` (신규)
+
+```typescript
+export function levenshteinDistance(a: string, b: string): number;
+export function levenshteinSimilarity(a: string, b: string): number;
+export function findBestFuzzyMatch(
+  needle: string,
+  haystack: string,
+  threshold: number
+): { start: number; end: number; score: number } | null;
+```
+
+**작업 항목**:
+- [ ] Levenshtein 거리 함수
+- [ ] 유사도 함수 (1 - distance / max_length)
+- [ ] 슬라이딩 윈도우 최적 매칭
+
+### 5.2 위치 역추적
+
+```typescript
+// 정규화된 문자열에서 원본 문자열 위치 매핑
+interface PositionMap {
+  normalizedToOriginal: Map<number, number>;
+  originalToNormalized: Map<number, number>;
+}
+
+export function createPositionMap(original: string, normalized: string): PositionMap;
+export function mapSpanToOriginal(map: PositionMap, normalizedSpan: Span): Span;
+```
+
+**작업 항목**:
+- [ ] 위치 매핑 생성 함수
+- [ ] span 역추적 함수
+
+## 파일 목록
+
+### 수정 파일
+```
+src/core/types.ts              # 타입 추가
+src/core/evidence-aligner.ts   # V2 로직 추가
+src/core/graduation.ts         # 승격 조건 수정
+src/core/event-store.ts        # 이벤트 타입 추가
+```
+
+### 신규 파일
+```
+src/core/string-utils.ts       # 문자열 유틸리티
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **Exact Match**
+   ```typescript
+   // quote가 원문에 정확히 존재
+   const source = "DuckDB의 JSONB를 JSON으로 변경";
+   const quote = "JSONB를 JSON으로";
+   expect(aligner.exactMatch(quote, source)).toEqual({
+     spanStart: 7,
+     spanEnd: 18,
+     confidence: 1.0,
+     matchMethod: 'exact'
+   });
+   ```
+
+2. **Normalized Match**
+   ```typescript
+   // 공백 차이만 있는 경우
+   const source = "JSONB를   JSON으로\n변경";
+   const quote = "JSONB를 JSON으로 변경";
+   expect(aligner.normalizedMatch(quote, source)).not.toBeNull();
+   ```
+
+3. **Fuzzy Match**
+   ```typescript
+   // 약간의 오타/변형
+   const source = "DuckDB에서 JSONB 타입을 제거";
+   const quote = "DuckDB JSONB 타입 제거";  // 조사 누락
+   const result = aligner.fuzzyMatch(quote, source, 0.85);
+   expect(result?.confidence).toBeGreaterThanOrEqual(0.85);
+   ```
+
+4. **No Match**
+   ```typescript
+   // 원문에 없는 내용
+   const source = "벡터 검색을 구현합니다";
+   const quote = "JSONB를 제거";
+   expect(aligner.align([source], { evidence: [{ quote }] })).toEqual({
+     evidenceAligned: false,
+     failedQuotes: ["JSONB를 제거"]
+   });
+   ```
+
+5. **승격 거부**
+   ```typescript
+   const entry = { evidenceAligned: false, stage: 'candidate' };
+   const result = await graduation.promoteToVerified(entry);
+   expect(result.success).toBe(false);
+   expect(result.reason).toContain('Evidence alignment failed');
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 타입 정의 완료 |
+| M2 | exactMatch + normalizedMatch 동작 |
+| M3 | fuzzyMatch 동작 (Levenshtein) |
+| M4 | evidence_aligned 이벤트 발행 |
+| M5 | Graduation 승격 조건 적용 |
+| M6 | 테스트 통과 |
+
+## 2026-02-25T12:31:26.323Z | c69c59bf-5958-4142-88c8-caa241ae54ae
+- type: session_summary
+- session: import:organized
+# Evidence Aligner V2 Specification
+
+> **Version**: 2.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 LLM이 evidence의 spanStart/spanEnd를 직접 계산하는 방식의 문제:
+
+1. **부정확한 오프셋**: LLM이 문자 위치를 정확히 계산하기 어려움
+2. **환각 가능성**: 원문에 없는 내용을 증거로 제시할 수 있음
+3. **검증 불가**: LLM이 준 오프셋이 실제 원문과 일치하는지 확인 어려움
+
+### 1.2 해결 방향
+
+**Quote-only 방식**:
+- LLM은 **quote(인용문)**만 제공
+- Pipeline(EvidenceAligner)이 원문에서 정확한 span 계산
+- 매칭 실패 시 `evidenceAligned=false`로 표시 → Verified 승격 금지
+
+## 2. 핵심 개념
+
+### 2.1 Evidence 흐름
+
+```
+LLM Extractor                    EvidenceAligner               Database
+     │                                  │                          │
+     │  { quote: "JSONB 제거" }         │                          │
+     ├─────────────────────────────────▶│                          │
+     │                                  │  원문에서 검색            │
+     │                                  │  ─────────────           │
+     │                                  │                          │
+     │  { spanStart: 142,               │                          │
+     │    spanEnd: 150,                 │                          │
+     │    confidence: 1.0 }             │                          │
+     │◀─────────────────────────────────┤                          │
+     │                                  │                          │
+     │                                  │  evidence_aligned 이벤트  │
+     │                                  ├─────────────────────────▶│
+```
+
+### 2.2 Extractor 출력 스키마 변경
+
+**기존 (금지)**:
+```json
+{
+  "evidence": [{
+    "messageIndex": 3,
+    "spanStart": 142,
+    "spanEnd": 150
+  }]
+}
+```
+
+**신규 (권장)**:
+```json
+{
+  "evidence": [{
+    "messageIndex": 3,
+    "quote": "content JSONB → JSON"
+  }]
+}
+```
+
+### 2.3 정렬 알고리즘
+
+```typescript
+interface AlignmentStep {
+  method: 'exact' | 'normalized' | 'fuzzy';
+  description: string;
+}
+
+const ALIGNMENT_STEPS: AlignmentStep[] = [
+  { method: 'exact', description: '정확한 substring 매칭' },
+  { method: 'normalized', description: '공백/개행 정규화 후 매칭' },
+  { method: 'fuzzy', description: 'Levenshtein 거리 기반 유사 매칭 (threshold: 0.85)' }
+];
+```
+
+## 3. 입출력 스키마
+
+### 3.1 입력
+
+```typescript
+interface AlignInput {
+  sessionMessages: string[];      // 원문 메시지 배열
+  extractedJson: ExtractedData;   // LLM 추출 결과
+}
+
+interface ExtractedEvidence {
+  messageIndex: number;
+  quote: string;                  // 30~200자 권장
+}
+```
+
+### 3.2 출력
+
+```typescript
+interface AlignedEvidence {
+  messageIndex: number;
+  quote: string;
+  quoteHash: string;              // SHA256(quote)
+  spanStart: number;              // 원문 내 시작 위치
+  spanEnd: number;                // 원문 내 끝 위치
+  confidence: number;             // 0.0 ~ 1.0
+  matchMethod: 'exact' | 'normalized' | 'fuzzy' | 'none';
+}
+
+interface AlignResult {
+  evidenceAligned: boolean;       // 모든 evidence가 정렬됨
+  alignedEvidence: AlignedEvidence[];
+  failedQuotes: string[];         // 정렬 실패한 quote 목록
+}
+```
+
+## 4. 정렬 로직 상세
+
+### 4.1 Exact Match
+
+```typescript
+function exactMatch(quote: string, source: string): AlignedSpan | null {
+  const index = source.indexOf(quote);
+  if (index === -1) return null;
+
+  return {
+    spanStart: index,
+    spanEnd: index + quote.length,
+    confidence: 1.0,
+    matchMethod: 'exact'
+  };
+}
+```
+
+### 4.2 Normalized Match
+
+```typescript
+function normalizedMatch(quote: string, source: string): AlignedSpan | null {
+  const normalizedQuote = normalize(quote);
+  const normalizedSource = normalize(source);
+
+  const index = normalizedSource.indexOf(normalizedQuote);
+  if (index === -1) return null;
+
+  // 원본 source에서 실제 위치 역추적 필요
+  const originalSpan = mapToOriginal(source, normalizedSource, index, normalizedQuote.length);
+
+  return {
+    ...originalSpan,
+    confidence: 0.95,
+    matchMethod: 'normalized'
+  };
+}
+
+function normalize(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')     // 연속 공백 → 단일 공백
+    .replace(/\n+/g, ' ')     // 개행 → 공백
+    .trim()
+    .toLowerCase();
+}
+```
+
+### 4.3 Fuzzy Match
+
+```typescript
+function fuzzyMatch(
+  quote: string,
+  source: string,
+  threshold: number = 0.85
+): AlignedSpan | null {
+  const normalizedQuote = normalize(quote);
+  const windowSize = Math.ceil(normalizedQuote.length * 1.2);
+
+  let bestMatch: { start: number; end: number; score: number } | null = null;
+
+  // 슬라이딩 윈도우로 유사도 검사
+  for (let i = 0; i <= source.length - windowSize; i++) {
+    const window = normalize(source.slice(i, i + windowSize));
+    const score = levenshteinSimilarity(normalizedQuote, window);
+
+    if (score >= threshold && (!bestMatch || score > bestMatch.score)) {
+      bestMatch = { start: i, end: i + windowSize, score };
+    }
+  }
+
+  if (!bestMatch) return null;
+
+  return {
+    spanStart: bestMatch.start,
+    spanEnd: bestMatch.end,
+    confidence: bestMatch.score,
+    matchMethod: 'fuzzy'
+  };
+}
+```
+
+## 5. 이벤트 스키마
+
+### 5.1 evidence_aligned 이벤트
+
+```typescript
+interface EvidenceAlignedEvent {
+  event_type: 'evidence_aligned';
+  session_id: string;
+  payload: {
+    source_event_id: string;        // session_ingested event
+    extraction_event_id: string;    // memory_extracted event
+    entry_id: string;
+    aligned_count: number;
+    failed_count: number;
+    evidence: AlignedEvidence[];
+    failed_quotes: string[];
+  };
+}
+```
+
+## 6. Idris2 영감 적용
+
+### 6.1 증거 기반 타입 (Proof-Carrying)
+
+**Idris2 개념**:
+```idris
+-- 타입이 증거를 포함
+data EvidencedFact : Type where
+  MkFact : (claim : String) -> (proof : Span) -> EvidencedFact
+```
+
+**TypeScript 적용**:
+```typescript
+// Discriminated Union으로 증거 유무 구분
+type Evidence =
+  | { aligned: true; span: AlignedSpan }
+  | { aligned: false; failureReason: string };
+
+// 증거가 있는 entry만 Verified로 승격 가능
+type VerifiedEntry = {
+  evidence: Extract<Evidence, { aligned: true }>[];  // 모든 evidence가 aligned
+};
+```
+
+### 6.2 불변식
+
+```typescript
+// Zod로 불변식 검증
+const AlignedEvidenceSchema = z.object({
+  confidence: z.number().min(0).max(1),
+  matchMethod: z.enum(['exact', 'normalized', 'fuzzy']),
+  // fuzzy면 confidence < 1.0
+}).refine(
+  (e) => e.matchMethod !== 'exact' || e.confidence === 1.0,
+  { message: 'Exact match must have confidence 1.0' }
+);
+```
+
+## 7. 승격 정책
+
+### 7.1 Evidence 기반 승격 조건
+
+| Stage | Evidence 요구사항 |
+|-------|------------------|
+| raw → working | 없음 |
+| working → candidate | 없음 |
+| candidate → verified | **evidenceAligned=true** 필수 |
+| verified → certified | 추가 검증 필요 |
+
+### 7.2 실패 처리
+
+```typescript
+async function processEntry(entry: Entry): Promise<void> {
+  const alignResult = await aligner.align(sessionMessages, entry.evidence);
+
+  if (!alignResult.evidenceAligned) {
+    // Verified 승격 금지
+    entry.meta.promotionBlocked = true;
+    entry.meta.promotionBlockReason = 'Evidence alignment failed';
+    entry.meta.failedQuotes = alignResult.failedQuotes;
+  }
+}
+```
+
+## 8. 기존 EvidenceAligner와 차이점
+
+### 8.1 현재 구현 (src/core/evidence-aligner.ts)
+
+```typescript
+// 현재: quote 기반 정렬 지원
+align(claims: string[], sourceContent: string): AlignmentResult {
+  // exact match만 지원
+  const exactSpan = this.findExactMatch(claim, sourceContent);
+}
+```
+
+### 8.2 V2 개선사항
+
+| 항목 | 현재 | V2 |
+|------|-----|-----|
+| 정규화 매칭 | 없음 | 공백/개행 정규화 |
+| Fuzzy 매칭 | 없음 | Levenshtein 기반 (threshold 0.85) |
+| 이벤트 기록 | 없음 | evidence_aligned 이벤트 발행 |
+| 승격 연동 | 없음 | evidenceAligned → Verified 조건 |
+| 메시지 인덱스 | 없음 | messageIndex 기반 정확한 소스 식별 |
+
+## 9. 성공 기준
+
+- [ ] LLM Extractor가 quote만 출력하도록 프롬프트 수정
+- [ ] EvidenceAligner가 3단계 정렬 (exact → normalized → fuzzy) 수행
+- [ ] 정렬 결과가 evidence_aligned 이벤트로 기록됨
+- [ ] evidenceAligned=false인 entry는 Verified 승격 불가
+- [ ] 기존 evidence-aligner.ts와 호환 유지