claude-memory-layer 1.0.0

package/specs/evidence-aligner-v2/context.md

@@ -0,0 +1,401 @@
+# 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 - 증거 범위 확정

package/specs/evidence-aligner-v2/plan.md

@@ -0,0 +1,303 @@
+# 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 | 테스트 통과 |