claude-memory-layer 1.0.0

package/specs/entity-edge-model/plan.md

@@ -0,0 +1,459 @@
+# Entity-Edge Model Implementation Plan
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## Phase 1: 스키마 정의 (P0)
+
+### 1.1 타입 정의
+
+**파일**: `src/core/types.ts` 수정
+
+```typescript
+// 추가할 타입들
+export const NodeTypeSchema = z.enum(['entry', 'entity', 'event']);
+export type NodeType = z.infer<typeof NodeTypeSchema>;
+
+export const RelationTypeSchema = z.enum([
+  // Entry ↔ Entry
+  'derived_from',
+  'supersedes',
+  'contradicts',
+  // Entry ↔ Entity
+  'evidence_of',
+  'mentions',
+  // Entity ↔ Entity
+  'blocked_by',
+  'blocked_by_suggested',
+  'resolves_to',
+  'depends_on',
+  // Event ↔ Entry/Entity
+  'produced',
+  'source_of'
+]);
+export type RelationType = z.infer<typeof RelationTypeSchema>;
+
+export const EdgeSchema = z.object({
+  edgeId: z.string(),
+  srcType: NodeTypeSchema,
+  srcId: z.string(),
+  relType: RelationTypeSchema,
+  dstType: NodeTypeSchema,
+  dstId: z.string(),
+  metaJson: z.record(z.unknown()).optional(),
+  createdAt: z.date()
+});
+export type Edge = z.infer<typeof EdgeSchema>;
+```
+
+**작업 항목**:
+- [ ] NodeType 스키마 추가
+- [ ] RelationType 스키마 추가
+- [ ] Edge 스키마 추가
+- [ ] EdgeMeta 타입들 추가 (EvidenceOfMeta, BlockedByMeta 등)
+
+### 1.2 DB 스키마
+
+**파일**: 마이그레이션 스크립트
+
+```sql
+-- 신규 테이블
+CREATE TABLE edges (...);
+
+-- entries 테이블 수정 (필요시)
+ALTER TABLE entries ADD COLUMN IF NOT EXISTS superseded_by VARCHAR;
+
+-- 인덱스
+CREATE INDEX idx_edges_src ON edges(src_id, rel_type);
+CREATE INDEX idx_edges_dst ON edges(dst_id, rel_type);
+CREATE UNIQUE INDEX idx_edges_unique ON edges(src_type, src_id, rel_type, dst_type, dst_id);
+```
+
+**작업 항목**:
+- [ ] edges 테이블 DDL
+- [ ] 인덱스 생성
+- [ ] 중복 방지 unique 인덱스
+
+## Phase 2: EdgeRepository 구현 (P0)
+
+### 2.1 기본 CRUD
+
+**파일**: `src/core/edge-repo.ts` (신규)
+
+```typescript
+export class EdgeRepository {
+  constructor(private db: Database);
+
+  async create(edge: EdgeInput): Promise<Edge> {
+    const edgeId = uuidv4();
+    await this.db.run(`
+      INSERT INTO edges (edge_id, src_type, src_id, rel_type, dst_type, dst_id, meta_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `, [edgeId, edge.srcType, edge.srcId, edge.relType, edge.dstType, edge.dstId,
+        JSON.stringify(edge.metaJson || {})]);
+    return { edgeId, ...edge, createdAt: new Date() };
+  }
+
+  async createMany(edges: EdgeInput[]): Promise<Edge[]> {
+    // 배치 insert
+  }
+}
+```
+
+**작업 항목**:
+- [ ] create() 메서드
+- [ ] createMany() 배치 메서드
+- [ ] findById() 메서드
+- [ ] findBySrc() 메서드
+- [ ] findByDst() 메서드
+
+### 2.2 삭제 및 교체
+
+```typescript
+async deleteBySrc(srcId: string, relType: string): Promise<number> {
+  const result = await this.db.run(`
+    DELETE FROM edges WHERE src_id = ? AND rel_type = ?
+  `, [srcId, relType]);
+  return result.changes;
+}
+
+async replaceBySrc(
+  srcId: string,
+  relType: string,
+  newEdges: EdgeInput[]
+): Promise<void> {
+  await this.db.transaction(async (tx) => {
+    await tx.run('DELETE FROM edges WHERE src_id = ? AND rel_type = ?', [srcId, relType]);
+    for (const edge of newEdges) {
+      await tx.run('INSERT INTO edges ...', [...]);
+    }
+  });
+}
+```
+
+**작업 항목**:
+- [ ] deleteById() 메서드
+- [ ] deleteBySrc() 메서드
+- [ ] replaceBySrc() 트랜잭션 메서드
+- [ ] exists() 중복 확인 메서드
+
+### 2.3 유효성 검증
+
+```typescript
+// 유효한 관계 조합만 허용
+const VALID_EDGE_PATTERNS = [
+  { srcType: 'entry', relType: 'evidence_of', dstType: 'entity' },
+  { srcType: 'entry', relType: 'derived_from', dstType: 'entry' },
+  { srcType: 'entity', relType: 'blocked_by', dstType: 'entity' },
+  // ...
+];
+
+function validateEdge(edge: EdgeInput): boolean {
+  return VALID_EDGE_PATTERNS.some(p =>
+    p.srcType === edge.srcType &&
+    p.relType === edge.relType &&
+    p.dstType === edge.dstType
+  );
+}
+```
+
+**작업 항목**:
+- [ ] 유효 패턴 정의
+- [ ] validateEdge() 함수
+- [ ] create() 호출 시 검증 적용
+
+## Phase 3: 뷰 및 쿼리 (P0)
+
+### 3.1 Effective Blockers 뷰
+
+**파일**: SQL 마이그레이션
+
+```sql
+CREATE VIEW v_task_blockers_effective AS
+WITH blocked AS (
+  SELECT
+    ed.src_id AS task_id,
+    ed.dst_id AS blocker_id,
+    ent.entity_type AS blocker_type,
+    ed.meta_json
+  FROM edges ed
+  JOIN entities ent ON ent.entity_id = ed.dst_id
+  WHERE ed.src_type = 'entity'
+    AND ed.rel_type = 'blocked_by'
+),
+resolved AS (
+  SELECT
+    b.task_id,
+    COALESCE(r.dst_id, b.blocker_id) AS effective_blocker_id,
+    COALESCE(
+      (SELECT entity_type FROM entities WHERE entity_id = r.dst_id),
+      b.blocker_type
+    ) AS effective_blocker_type
+  FROM blocked b
+  LEFT JOIN edges r ON r.src_type = 'entity'
+                   AND r.src_id = b.blocker_id
+                   AND r.rel_type = 'resolves_to'
+)
+SELECT * FROM resolved;
+```
+
+**작업 항목**:
+- [ ] v_task_blockers_effective 뷰 생성
+
+### 3.2 조회 함수
+
+**파일**: `src/core/queries.ts` (신규 또는 기존 확장)
+
+```typescript
+// Task의 effective blockers 조회
+async function getEffectiveBlockers(taskId: string): Promise<EffectiveBlocker[]> {
+  return db.query(`
+    SELECT * FROM v_task_blockers_effective WHERE task_id = ?
+  `, [taskId]);
+}
+
+// Entry의 증거 체인 조회
+async function getEvidenceChain(entryId: string): Promise<Evidence[]> {
+  return db.query(`
+    SELECT ent.*, ed.meta_json as evidence_meta
+    FROM entities ent
+    JOIN edges ed ON ed.dst_id = ent.entity_id
+    WHERE ed.src_type = 'entry' AND ed.src_id = ?
+      AND ed.rel_type = 'evidence_of'
+  `, [entryId]);
+}
+```
+
+**작업 항목**:
+- [ ] getEffectiveBlockers() 함수
+- [ ] getEvidenceChain() 함수
+- [ ] getBlockedTasks() 함수
+- [ ] getResolvedConditions() 함수
+
+## Phase 4: Projector 연동 (P0)
+
+### 4.1 TaskProjector 수정
+
+**파일**: `src/core/task-projector.ts`
+
+```typescript
+// mode=replace 처리
+async handleBlockersSet(event: TaskEvent): Promise<void> {
+  const payload = event.payload as TaskBlockersSetPayload;
+
+  if (payload.mode === 'replace') {
+    // 기존 blocked_by edge 모두 삭제
+    await this.edgeRepo.deleteBySrc(payload.task_id, 'blocked_by');
+
+    // 새 edge 생성
+    for (const blocker of payload.blockers) {
+      await this.edgeRepo.create({
+        srcType: 'entity',
+        srcId: payload.task_id,
+        relType: 'blocked_by',
+        dstType: 'entity',
+        dstId: blocker.entity_id,
+        metaJson: {
+          mode: 'replace',
+          raw_text: blocker.raw_text,
+          confidence: blocker.confidence
+        }
+      });
+    }
+  } else if (payload.mode === 'suggest') {
+    // blocked_by_suggested edge만 추가/갱신
+    await this.edgeRepo.replaceBySrc(
+      payload.task_id,
+      'blocked_by_suggested',
+      payload.blockers.map(b => ({
+        srcType: 'entity',
+        srcId: payload.task_id,
+        relType: 'blocked_by_suggested',
+        dstType: 'entity',
+        dstId: b.entity_id,
+        metaJson: { raw_text: b.raw_text }
+      }))
+    );
+  }
+}
+```
+
+**작업 항목**:
+- [ ] handleBlockersSet에서 edge 생성
+- [ ] mode=replace 처리
+- [ ] mode=suggest 처리
+- [ ] handleStatusChanged에서 done 시 edge 삭제
+
+### 4.2 Evidence Edge 생성
+
+**파일**: `src/core/graduation.ts` 또는 별도 projector
+
+```typescript
+// Entry 저장 시 evidence edge 생성
+async function materializeEntry(entry: Entry, alignResult: AlignResult): Promise<void> {
+  // Entry 저장
+  await entryRepo.create(entry);
+
+  // Evidence edge 생성
+  for (const ev of alignResult.alignedEvidence) {
+    if (ev.matchMethod !== 'none') {
+      // Entity 찾기 또는 생성
+      const entity = await resolveEvidenceTarget(ev);
+
+      await edgeRepo.create({
+        srcType: 'entry',
+        srcId: entry.entry_id,
+        relType: 'evidence_of',
+        dstType: 'entity',
+        dstId: entity.entity_id,
+        metaJson: {
+          confidence: ev.confidence,
+          span: { start: ev.spanStart, end: ev.spanEnd },
+          alignment_method: ev.matchMethod
+        }
+      });
+    }
+  }
+}
+```
+
+**작업 항목**:
+- [ ] Entry 저장 시 evidence edge 생성
+- [ ] source_of edge 생성 (세션 이벤트 연결)
+
+## Phase 5: 마이그레이션 (P1)
+
+### 5.1 기존 데이터 변환 스크립트
+
+**파일**: `scripts/migrate-to-edges.ts`
+
+```typescript
+async function migrateExistingData(): Promise<MigrationResult> {
+  const stats = { entries: 0, edges: 0, errors: 0 };
+
+  // 1. evidence_json → evidence_of edge
+  const entriesWithEvidence = await db.query(`
+    SELECT * FROM entries WHERE evidence_json IS NOT NULL
+  `);
+
+  for (const entry of entriesWithEvidence) {
+    try {
+      const evidence = JSON.parse(entry.evidence_json);
+      // ... edge 생성
+      stats.edges++;
+    } catch (e) {
+      stats.errors++;
+    }
+  }
+
+  // 2. Task blockers → blocked_by edge
+  const tasks = await db.query(`
+    SELECT * FROM entities WHERE entity_type = 'task'
+  `);
+
+  for (const task of tasks) {
+    const currentJson = JSON.parse(task.current_json);
+    if (currentJson.blockers) {
+      // ... edge 생성
+    }
+  }
+
+  return stats;
+}
+```
+
+**작업 항목**:
+- [ ] evidence_json → edge 변환
+- [ ] Task blockers → edge 변환
+- [ ] 변환 통계 리포트
+- [ ] 롤백 스크립트
+
+### 5.2 이중 쓰기 기간
+
+```typescript
+// 마이그레이션 기간 동안 JSON과 edge 모두 기록
+async function createBlockerWithDualWrite(
+  taskId: string,
+  blockers: BlockerRef[]
+): Promise<void> {
+  // 1. 기존 방식: current_json에 blockers 저장
+  await entityRepo.updateCurrentState(taskId, { blockers });
+
+  // 2. 신규 방식: edge 생성
+  for (const b of blockers) {
+    await edgeRepo.create({ ... });
+  }
+}
+```
+
+**작업 항목**:
+- [ ] 이중 쓰기 래퍼 함수
+- [ ] 마이그레이션 완료 후 JSON 쓰기 제거
+
+## 파일 목록
+
+### 신규 파일
+```
+src/core/edge-repo.ts         # Edge CRUD
+src/core/queries.ts           # 복합 쿼리 함수
+scripts/migrate-to-edges.ts   # 마이그레이션 스크립트
+```
+
+### 수정 파일
+```
+src/core/types.ts             # Edge 타입 추가
+src/core/task-projector.ts    # Edge 생성 연동
+src/core/graduation.ts        # Evidence edge 생성
+```
+
+## 테스트
+
+### 필수 테스트 케이스
+
+1. **Edge 생성 유효성**
+   ```typescript
+   // 유효한 조합
+   await edgeRepo.create({
+     srcType: 'entry', relType: 'evidence_of', dstType: 'entity', ...
+   }); // OK
+
+   // 무효한 조합
+   await edgeRepo.create({
+     srcType: 'entry', relType: 'blocked_by', dstType: 'entry', ...
+   }); // Error
+   ```
+
+2. **중복 방지**
+   ```typescript
+   await edgeRepo.create({ srcId: 'a', dstId: 'b', relType: 'evidence_of', ... });
+   await edgeRepo.create({ srcId: 'a', dstId: 'b', relType: 'evidence_of', ... });
+   // 두 번째는 무시 또는 에러
+   ```
+
+3. **replace 동작**
+   ```typescript
+   await edgeRepo.replaceBySrc('task1', 'blocked_by', [
+     { dstId: 'blocker1' },
+     { dstId: 'blocker2' }
+   ]);
+   // 기존 blocked_by edge 모두 삭제 후 새로 생성
+   ```
+
+4. **Effective blockers**
+   ```typescript
+   // Condition → Task로 resolve된 경우
+   // v_task_blockers_effective에서 Task가 effective blocker로 나와야 함
+   ```
+
+## 마일스톤
+
+| 단계 | 완료 기준 |
+|------|----------|
+| M1 | 타입 정의 + edges 테이블 생성 |
+| M2 | EdgeRepository 기본 CRUD |
+| M3 | v_task_blockers_effective 뷰 |
+| M4 | TaskProjector edge 연동 |
+| M5 | Evidence edge 생성 |
+| M6 | 마이그레이션 스크립트 |
+| M7 | 테스트 통과 |