claude-memory-layer 1.0.0

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

@@ -0,0 +1,391 @@
+# Entity-Edge Model Specification
+
+> **Version**: 1.0.0
+> **Status**: Draft
+> **Created**: 2026-01-31
+
+## 1. 개요
+
+### 1.1 문제 정의
+
+현재 시스템에서 데이터 관계가 명시적으로 모델링되지 않음:
+
+1. **Entry 간 관계 없음**: Fact와 이를 지지하는 Decision이 분리됨
+2. **Entity 관계 없음**: Task와 Blocker 간 관계가 JSON 내부에만 존재
+3. **증거 추적 불가**: Entry가 어떤 세션에서 왔는지 추적 어려움
+
+### 1.2 해결 방향
+
+**entries / entities / edges 분리**:
+- `entries`: 불변 기록 (Fact, Decision, Insight 등)
+- `entities`: 상태 변화 개체 (Task, Condition, Artifact)
+- `edges`: 관계 그래프 (evidence_of, blocked_by 등)
+
+## 2. 핵심 개념
+
+### 2.1 3-Layer 모델
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        edges                                 │
+│  ┌──────────┐    evidence_of    ┌──────────┐               │
+│  │  Entry   │ ─────────────────▶│  Entity  │               │
+│  └──────────┘                   └──────────┘               │
+│       │                              │                       │
+│       │ derived_from                 │ blocked_by           │
+│       ▼                              ▼                       │
+│  ┌──────────┐                   ┌──────────┐               │
+│  │  Entry   │                   │  Entity  │               │
+│  └──────────┘                   └──────────┘               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Node 타입
+
+| 타입 | 테이블 | 예시 |
+|-----|--------|-----|
+| entry | entries | Fact, Decision, Insight, TaskNote |
+| entity | entities | Task, Condition, Artifact |
+| event | events | session_ingested, memory_extracted |
+
+### 2.3 관계 타입
+
+```typescript
+type RelationType =
+  // Entry ↔ Entry
+  | 'derived_from'        // 이 Entry가 다른 Entry에서 파생됨
+  | 'supersedes'          // 이 Entry가 다른 Entry를 대체함
+  | 'contradicts'         // 이 Entry가 다른 Entry와 모순됨
+
+  // Entry ↔ Entity
+  | 'evidence_of'         // Entry가 Entity의 증거
+  | 'mentions'            // Entry가 Entity를 언급
+
+  // Entity ↔ Entity
+  | 'blocked_by'          // Task가 다른 Entity에 의해 blocked
+  | 'blocked_by_suggested'// 제안된 blocker (미확정)
+  | 'resolves_to'         // Condition이 실제 Entity로 해결됨
+  | 'depends_on'          // 일반적인 의존 관계
+
+  // Event ↔ Entry/Entity
+  | 'produced'            // Event가 Entry/Entity를 생성함
+  | 'source_of'           // Event가 증거의 원본 소스
+```
+
+## 3. DB 스키마
+
+### 3.1 entries 테이블
+
+```sql
+CREATE TABLE entries (
+  entry_id      VARCHAR PRIMARY KEY,
+  created_ts    TIMESTAMP NOT NULL,
+  entry_type    VARCHAR NOT NULL,        -- fact|decision|insight|task_note|reference
+  title         VARCHAR NOT NULL,
+  content_json  JSON NOT NULL,
+  stage         VARCHAR NOT NULL,        -- raw|working|candidate|verified|certified
+  status        VARCHAR DEFAULT 'active',-- active|contested|deprecated|superseded
+  superseded_by VARCHAR,                 -- 대체된 경우 새 entry_id
+  build_id      VARCHAR,
+  evidence_json JSON,                    -- aligned spans
+  canonical_key VARCHAR,
+  created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_entries_type ON entries(entry_type);
+CREATE INDEX idx_entries_stage ON entries(stage);
+CREATE INDEX idx_entries_status ON entries(status);
+CREATE INDEX idx_entries_canonical ON entries(canonical_key);
+```
+
+### 3.2 entities 테이블
+
+```sql
+CREATE TABLE entities (
+  entity_id      VARCHAR PRIMARY KEY,
+  entity_type    VARCHAR NOT NULL,       -- task|condition|artifact
+  canonical_key  VARCHAR NOT NULL,
+  title          VARCHAR NOT NULL,
+  stage          VARCHAR NOT NULL,       -- raw|working|candidate|verified|certified
+  status         VARCHAR NOT NULL,       -- active|contested|deprecated|superseded
+  current_json   JSON NOT NULL,          -- fold된 현재 상태
+  title_norm     VARCHAR,                -- 정규화된 제목 (검색용)
+  search_text    VARCHAR,                -- FTS용 텍스트
+  created_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE UNIQUE INDEX idx_entities_type_key ON entities(entity_type, canonical_key);
+CREATE INDEX idx_entities_status ON entities(status);
+```
+
+### 3.3 edges 테이블
+
+```sql
+CREATE TABLE edges (
+  edge_id     VARCHAR PRIMARY KEY,
+  src_type    VARCHAR NOT NULL,  -- entry|entity|event
+  src_id      VARCHAR NOT NULL,
+  rel_type    VARCHAR NOT NULL,  -- evidence_of|blocked_by|...
+  dst_type    VARCHAR NOT NULL,  -- entry|entity|event
+  dst_id      VARCHAR NOT NULL,
+  meta_json   JSON,              -- 관계 메타데이터
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 복합 인덱스
+CREATE INDEX idx_edges_src ON edges(src_id, rel_type);
+CREATE INDEX idx_edges_dst ON edges(dst_id, rel_type);
+CREATE INDEX idx_edges_rel ON edges(rel_type);
+
+-- 중복 방지 (동일 관계 재생성 방지)
+CREATE UNIQUE INDEX idx_edges_unique ON edges(src_type, src_id, rel_type, dst_type, dst_id);
+```
+
+## 4. Edge 메타데이터
+
+### 4.1 evidence_of
+
+```typescript
+interface EvidenceOfMeta {
+  confidence: number;        // 증거 신뢰도
+  span?: {
+    start: number;
+    end: number;
+  };
+  alignment_method: 'exact' | 'normalized' | 'fuzzy';
+  source_event_id: string;   // 원본 세션 이벤트
+}
+```
+
+### 4.2 blocked_by
+
+```typescript
+interface BlockedByMeta {
+  mode: 'replace' | 'suggest';
+  raw_text: string;          // 원본 텍스트
+  resolved_at?: Date;        // 해결된 시간
+  resolved_by?: string;      // 해결한 세션
+}
+```
+
+### 4.3 resolves_to
+
+```typescript
+interface ResolvesToMeta {
+  resolution_type: 'exact_match' | 'user_confirmed' | 'auto_resolved';
+  confidence: number;
+  resolved_at: Date;
+}
+```
+
+## 5. 쿼리 패턴
+
+### 5.1 Entity의 모든 증거 조회
+
+```sql
+SELECT e.*, ed.meta_json
+FROM entries e
+JOIN edges ed ON ed.src_type = 'entry' AND ed.src_id = e.entry_id
+WHERE ed.rel_type = 'evidence_of'
+  AND ed.dst_type = 'entity'
+  AND ed.dst_id = :entity_id
+ORDER BY e.created_ts DESC;
+```
+
+### 5.2 Task의 effective blockers (Condition 해결 적용)
+
+```sql
+-- v_task_blockers_effective 뷰
+CREATE VIEW v_task_blockers_effective AS
+WITH blocked AS (
+  -- 직접 blocker
+  SELECT
+    ed.src_id AS task_id,
+    ed.dst_id AS blocker_id,
+    ed.dst_type AS blocker_type,
+    ed.meta_json
+  FROM edges ed
+  WHERE ed.src_type = 'entity'
+    AND ed.rel_type = 'blocked_by'
+),
+resolved AS (
+  -- Condition이 해결된 경우
+  SELECT
+    b.task_id,
+    COALESCE(r.dst_id, b.blocker_id) AS effective_blocker_id,
+    COALESCE(r.dst_type, 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;
+```
+
+### 5.3 Entry의 파생 체인 (lineage)
+
+```sql
+WITH RECURSIVE lineage AS (
+  -- Base: 시작 entry
+  SELECT entry_id, 0 AS depth
+  FROM entries
+  WHERE entry_id = :start_id
+
+  UNION ALL
+
+  -- Recursive: derived_from 관계 따라가기
+  SELECT e.src_id, l.depth + 1
+  FROM edges e
+  JOIN lineage l ON e.dst_id = l.entry_id
+  WHERE e.rel_type = 'derived_from'
+    AND l.depth < 10  -- 무한 루프 방지
+)
+SELECT * FROM lineage;
+```
+
+## 6. Idris2 영감 적용
+
+### 6.1 관계 타입 안전성
+
+```typescript
+// 타입 레벨에서 유효한 관계만 허용
+type ValidEdge =
+  | { srcType: 'entry'; relType: 'evidence_of'; dstType: 'entity' }
+  | { srcType: 'entry'; relType: 'derived_from'; dstType: 'entry' }
+  | { srcType: 'entity'; relType: 'blocked_by'; dstType: 'entity' }
+  | { srcType: 'entity'; relType: 'resolves_to'; dstType: 'entity' };
+
+// 잘못된 조합은 타입 에러
+// { srcType: 'entry'; relType: 'blocked_by'; dstType: 'entry' }  // Error!
+```
+
+### 6.2 Zod 스키마로 검증
+
+```typescript
+const EdgeSchema = z.discriminatedUnion('relType', [
+  z.object({
+    srcType: z.literal('entry'),
+    relType: z.literal('evidence_of'),
+    dstType: z.literal('entity')
+  }),
+  z.object({
+    srcType: z.literal('entity'),
+    relType: z.literal('blocked_by'),
+    dstType: z.literal('entity')
+  }),
+  // ...
+]);
+```
+
+### 6.3 불변식
+
+```typescript
+// blocked_by edge 생성 시 Task 상태도 blocked여야 함
+async function createBlockedByEdge(
+  taskId: string,
+  blockerId: string
+): Promise<Edge> {
+  const task = await entityRepo.findById(taskId);
+
+  // 불변식 검증
+  if (task.current_json.status !== 'blocked') {
+    throw new InvariantViolationError(
+      `Cannot create blocked_by edge: Task ${taskId} is not in blocked status`
+    );
+  }
+
+  return edgeRepo.create({
+    srcType: 'entity',
+    srcId: taskId,
+    relType: 'blocked_by',
+    dstType: 'entity',
+    dstId: blockerId
+  });
+}
+```
+
+## 7. EdgeRepository API
+
+```typescript
+interface EdgeRepository {
+  // 생성
+  create(edge: EdgeInput): Promise<Edge>;
+  createMany(edges: EdgeInput[]): Promise<Edge[]>;
+
+  // 조회
+  findById(edgeId: string): Promise<Edge | null>;
+  findBySrc(srcId: string, relType?: string): Promise<Edge[]>;
+  findByDst(dstId: string, relType?: string): Promise<Edge[]>;
+
+  // 삭제 (projector용)
+  deleteById(edgeId: string): Promise<void>;
+  deleteBySrc(srcId: string, relType: string): Promise<number>;
+
+  // 교체 (mode=replace용)
+  replaceBySrc(
+    srcId: string,
+    relType: string,
+    newEdges: EdgeInput[]
+  ): Promise<void>;
+
+  // 중복 확인
+  exists(
+    srcType: string,
+    srcId: string,
+    relType: string,
+    dstType: string,
+    dstId: string
+  ): Promise<boolean>;
+}
+```
+
+## 8. 마이그레이션 전략
+
+### 8.1 기존 데이터 변환
+
+```typescript
+// 기존 entry의 evidence → edges로 변환
+async function migrateEvidence(): Promise<void> {
+  const entries = await db.query('SELECT * FROM entries WHERE evidence_json IS NOT NULL');
+
+  for (const entry of entries) {
+    const evidence = JSON.parse(entry.evidence_json);
+
+    for (const ev of evidence) {
+      // Entity 찾기 (canonical_key 기반)
+      const entity = await entityRepo.findByCanonicalKey(
+        'task',
+        ev.canonical_key
+      );
+
+      if (entity) {
+        await edgeRepo.create({
+          srcType: 'entry',
+          srcId: entry.entry_id,
+          relType: 'evidence_of',
+          dstType: 'entity',
+          dstId: entity.entity_id,
+          metaJson: { confidence: ev.confidence, span: ev.span }
+        });
+      }
+    }
+  }
+}
+```
+
+### 8.2 점진적 적용
+
+1. **Phase 1**: edges 테이블 생성, 신규 데이터만 edge 기록
+2. **Phase 2**: 기존 데이터 마이그레이션 (백그라운드)
+3. **Phase 3**: 쿼리를 edges 기반으로 전환
+4. **Phase 4**: 기존 JSON 필드 deprecated
+
+## 9. 성공 기준
+
+- [ ] entries/entities/edges 3개 테이블 분리 동작
+- [ ] evidence_of edge로 Entry→Entity 증거 관계 추적
+- [ ] blocked_by edge로 Task 의존성 그래프 구축
+- [ ] resolves_to edge로 Condition→Entity 해결 추적
+- [ ] v_task_blockers_effective 뷰로 effective blocker 조회
+- [ ] 기존 JSON 기반 관계와 호환 유지