claude-memory-layer 1.0.31 → 1.0.32

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

@@ -1,401 +0,0 @@
-# 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

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