claude-memory-layer 1.0.0

package/specs/vector-outbox-v2/context.md

@@ -0,0 +1,470 @@
+# Vector Outbox V2 Context
+
+> **Version**: 2.0.0
+> **Created**: 2026-01-31
+
+## 1. 배경
+
+### 1.1 분산 시스템의 정합성 문제
+
+두 개의 서로 다른 저장소(DuckDB, LanceDB)에 데이터를 저장할 때:
+
+```
+Application
+    │
+    ├──▶ DuckDB (entries 저장) ✓
+    │
+    └──▶ LanceDB (벡터 저장) ✗ (실패)
+
+결과: DuckDB에는 있지만 LanceDB에는 없는 불일치 상태
+```
+
+**문제 시나리오**:
+1. Entry가 저장되었지만 임베딩이 실패
+2. 재시작 시 어떤 entry가 임베딩되지 않았는지 알 수 없음
+3. 검색 결과에서 해당 entry가 누락
+
+### 1.2 Transactional Outbox Pattern
+
+마이크로서비스 아키텍처에서 검증된 패턴:
+
+```
+┌─────────────────────────────────────┐
+│ DuckDB Transaction                   │
+│                                      │
+│  1. INSERT INTO entries (...)        │
+│  2. INSERT INTO vector_outbox (...)  │
+│                                      │
+│  COMMIT                              │
+└─────────────────────────────────────┘
+            │
+            │ (비동기)
+            ▼
+┌─────────────────────────────────────┐
+│ Vector Worker                        │
+│                                      │
+│  1. SELECT * FROM vector_outbox      │
+│     WHERE status = 'pending'         │
+│  2. Generate embedding               │
+│  3. Upsert to LanceDB                │
+│  4. UPDATE status = 'done'           │
+└─────────────────────────────────────┘
+```
+
+**장점**:
+- 원자성 보장 (DuckDB 트랜잭션 내)
+- 실패 시 재시도 가능
+- 상태 추적 가능
+
+## 2. Memo.txt 참고 사항
+
+### 2.1 핵심 원칙 (섹션 2.6)
+
+> **6. Vector store 정합성**
+> - DuckDB에 먼저 기록 → outbox → 단일 writer가 LanceDB에 upsert → DuckDB 상태 업데이트
+
+### 2.2 스키마 (섹션 4.4)
+
+```sql
+CREATE TABLE vector_outbox (
+  job_id            VARCHAR PRIMARY KEY,
+  item_kind         VARCHAR NOT NULL,        -- entry|task_title
+  item_id           VARCHAR NOT NULL,
+  embedding_version VARCHAR NOT NULL,
+  status            VARCHAR NOT NULL,        -- pending|done|failed
+  error             VARCHAR,
+  created_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at        TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(item_kind, item_id, embedding_version)
+);
+```
+
+### 2.3 Worker 지시 (섹션 8)
+
+**Outbox enqueue**:
+- entry materialized 시: `item_kind='entry'`
+- task_created/task_title_changed 시: `item_kind='task_title'`
+
+**Single writer worker**:
+- pending 배치 처리
+- LanceDB **idempotent upsert**
+- 같은 id는 중복 row가 쌓이지 않게
+
+**reconcile()**:
+- pending 재처리
+- failed는 재시도 정책
+
+## 3. Idris2 영감 적용
+
+### 3.1 상태 머신 타입 안전성
+
+**Idris2 개념**:
+```idris
+-- 상태 전이가 타입 수준에서 정의됨
+data OutboxState = Pending | Processing | Done | Failed
+
+data Transition : OutboxState -> OutboxState -> Type where
+  Claim    : Transition Pending Processing
+  Complete : Transition Processing Done
+  Fail     : Transition Processing Failed
+  Retry    : Transition Failed Pending
+```
+
+**TypeScript 적용**:
+```typescript
+// 유효한 전이만 타입으로 정의
+type ValidTransition =
+  | { from: 'pending'; to: 'processing' }
+  | { from: 'processing'; to: 'done' }
+  | { from: 'processing'; to: 'failed' }
+  | { from: 'failed'; to: 'pending' };
+
+// 런타임 검증
+function assertValidTransition(from: OutboxStatus, to: OutboxStatus): void {
+  const valid: ValidTransition[] = [...];
+  if (!valid.some(t => t.from === from && t.to === to)) {
+    throw new Error(`Invalid transition: ${from} → ${to}`);
+  }
+}
+```
+
+### 3.2 Idempotency 증명
+
+**Idris2 개념**:
+```idris
+-- 같은 입력에 같은 결과
+idempotent : (f : a -> a) -> Type
+idempotent f = (x : a) -> f (f x) = f x
+```
+
+**TypeScript 적용**:
+```typescript
+// UNIQUE 제약으로 idempotency 보장
+const UNIQUE_CONSTRAINT = `
+  UNIQUE(item_kind, item_id, embedding_version)
+`;
+
+// enqueue는 여러 번 호출해도 같은 결과
+async function enqueue(input: EnqueueInput): Promise<EnqueueResult> {
+  await db.run(`
+    INSERT INTO vector_outbox (...)
+    ON CONFLICT (item_kind, item_id, embedding_version)
+    DO NOTHING
+  `, [...]);
+  // 결과는 항상 동일: 하나의 job만 존재
+}
+```
+
+### 3.3 벡터 upsert 증명
+
+```typescript
+// upsert 후 조건: 정확히 하나의 레코드만 존재
+interface UpsertInvariant {
+  // Pre: record with id=X may or may not exist
+  // Post: exactly one record with id=X exists, with latest values
+}
+
+async function upsert(record: VectorRecord): Promise<void> {
+  // Delete existing (if any)
+  await table.delete(`id = '${record.id}'`);
+  // Insert new
+  await table.add([record]);
+  // Invariant: exactly one record with id exists
+}
+```
+
+## 4. 기존 코드와의 관계
+
+### 4.1 현재 vector-worker.ts
+
+```typescript
+// 현재 구현 (src/core/vector-worker.ts)
+export class VectorWorker {
+  private embedder: Embedder;
+  private vectorStore: VectorStore;
+  private db: Database;
+}
+
+export interface OutboxItem {
+  id: string;
+  eventId: string;
+  content: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  retryCount: number;
+  createdAt: Date;
+  errorMessage?: string;
+}
+```
+
+### 4.2 V2 확장 포인트
+
+| 기존 | V2 확장 |
+|-----|---------|
+| eventId 기반 | item_kind + item_id |
+| 단순 status | embedding_version 추가 |
+| 재시도 없음 | reconcile + retry policy |
+| 중복 가능 | UNIQUE + upsert |
+
+### 4.3 현재 types.ts
+
+```typescript
+// 현재 OutboxItem 정의
+export interface OutboxItem {
+  id: string;
+  eventId: string;
+  content: string;
+  status: 'pending' | 'processing' | 'done' | 'failed';
+  retryCount: number;
+  createdAt: Date;
+  errorMessage?: string;
+}
+```
+
+V2에서 OutboxJob으로 확장.
+
+## 5. 설계 결정 사항
+
+### 5.1 왜 embedding_version을 포함하는가?
+
+**시나리오**:
+1. 모델 v1으로 entry A 임베딩
+2. 모델 v2로 업그레이드
+3. entry A를 v2로 재임베딩 필요
+
+**해결**:
+```sql
+-- v1과 v2 job이 별도로 존재 가능
+UNIQUE(item_kind, item_id, embedding_version)
+
+-- v1 job
+(job_1, 'entry', 'e1', 'minilm-v1', 'done')
+
+-- v2 job
+(job_2, 'entry', 'e1', 'minilm-v2', 'pending')
+```
+
+### 5.2 왜 단일 writer인가?
+
+**문제**: 여러 프로세스가 동시에 LanceDB에 쓰면
+- 동일 id에 대해 race condition
+- delete와 add 사이에 다른 write 끼어들 수 있음
+- LanceDB 자체 락 메커니즘 미약
+
+**해결**:
+- 애플리케이션 레벨에서 단일 writer 보장
+- 파일 락 또는 DB 락 사용
+
+### 5.3 왜 delete + add인가?
+
+LanceDB가 true upsert를 지원하지 않기 때문:
+
+```typescript
+// 방법 1: update 시도 (LanceDB 제한적 지원)
+await table.update({ id: 'e1' }, { vector: newVector });  // 불완전
+
+// 방법 2: delete + add (권장)
+await table.delete(`id = 'e1'`);
+await table.add([{ id: 'e1', vector: newVector, ... }]);  // 확실
+```
+
+## 6. Reconcile 전략
+
+### 6.1 Failed Job 재시도
+
+```typescript
+const RETRY_POLICY = {
+  maxRetries: 3,
+  backoffMs: [1000, 5000, 30000]  // 1초, 5초, 30초
+};
+
+async function shouldRetry(job: OutboxJob): Promise<boolean> {
+  return job.retryCount < RETRY_POLICY.maxRetries;
+}
+
+async function reconcileFailed(): Promise<number> {
+  return db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        retry_count = retry_count + 1,
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'failed'
+      AND retry_count < ?
+  `, [RETRY_POLICY.maxRetries]);
+}
+```
+
+### 6.2 Stuck Job 복구
+
+Processing 상태에서 worker가 죽으면:
+
+```typescript
+const STUCK_THRESHOLD_MS = 5 * 60 * 1000;  // 5분
+
+async function recoverStuck(): Promise<number> {
+  const threshold = new Date(Date.now() - STUCK_THRESHOLD_MS);
+  return db.run(`
+    UPDATE vector_outbox
+    SET status = 'pending',
+        updated_at = CURRENT_TIMESTAMP
+    WHERE status = 'processing'
+      AND updated_at < ?
+  `, [threshold]);
+}
+```
+
+### 6.3 Done Job 정리
+
+저장 공간 관리:
+
+```typescript
+async function cleanupDone(olderThanDays: number = 7): Promise<number> {
+  return db.run(`
+    DELETE FROM vector_outbox
+    WHERE status = 'done'
+      AND updated_at < datetime('now', '-${olderThanDays} days')
+  `);
+}
+```
+
+## 7. 모니터링 및 알림
+
+### 7.1 메트릭
+
+```typescript
+interface OutboxMetrics {
+  pendingCount: number;
+  processingCount: number;
+  doneCount: number;
+  failedCount: number;
+  avgProcessingTimeMs: number;
+  oldestPendingAge: number;  // 가장 오래된 pending job의 나이 (ms)
+}
+```
+
+### 7.2 알림 조건
+
+```typescript
+const ALERT_THRESHOLDS = {
+  failedCount: 10,           // failed가 10개 이상
+  pendingAge: 60 * 60 * 1000 // pending이 1시간 이상 된 경우
+};
+
+async function checkAlerts(): Promise<Alert[]> {
+  const metrics = await getMetrics();
+  const alerts: Alert[] = [];
+
+  if (metrics.failedCount >= ALERT_THRESHOLDS.failedCount) {
+    alerts.push({
+      level: 'warning',
+      message: `${metrics.failedCount} vector jobs failed`
+    });
+  }
+
+  if (metrics.oldestPendingAge >= ALERT_THRESHOLDS.pendingAge) {
+    alerts.push({
+      level: 'warning',
+      message: `Oldest pending job is ${metrics.oldestPendingAge / 1000}s old`
+    });
+  }
+
+  return alerts;
+}
+```
+
+## 8. 에러 처리
+
+### 8.1 임베딩 실패
+
+```typescript
+try {
+  const embedding = await embedder.embed(content);
+} catch (error) {
+  if (error.message.includes('rate limit')) {
+    // 재시도 가능
+    throw new RetryableError('Rate limited', { retryAfterMs: 60000 });
+  } else if (error.message.includes('too long')) {
+    // 영구 실패
+    throw new PermanentError('Content too long for embedding');
+  }
+  throw error;
+}
+```
+
+### 8.2 LanceDB 실패
+
+```typescript
+try {
+  await vectorStore.upsert(record);
+} catch (error) {
+  if (error.message.includes('disk full')) {
+    throw new PermanentError('Disk full');
+  } else if (error.message.includes('connection')) {
+    throw new RetryableError('Connection failed');
+  }
+  throw error;
+}
+```
+
+### 8.3 콘텐츠 없음
+
+```typescript
+const content = await getContent(job.itemKind, job.itemId);
+if (!content) {
+  // Entry가 삭제되었거나 존재하지 않음
+  // Job을 done으로 마크하고 건너뜀
+  await markDone(job.jobId, { skipped: true, reason: 'content_not_found' });
+  return;
+}
+```
+
+## 9. 성능 고려사항
+
+### 9.1 배치 처리
+
+```typescript
+const BATCH_SIZE = 50;
+
+// 한 번에 여러 job claim
+const jobs = await claimJobs(BATCH_SIZE);
+
+// 임베딩도 배치로
+const contents = jobs.map(j => j.content);
+const embeddings = await embedder.embedBatch(contents);
+
+// LanceDB 배치 insert
+await vectorStore.addBatch(jobs.map((j, i) => ({
+  id: j.itemId,
+  vector: embeddings[i],
+  ...
+})));
+```
+
+### 9.2 병렬 처리 (주의)
+
+```typescript
+// 단일 writer 내에서 병렬 처리
+// LanceDB 쓰기는 순차적으로, 임베딩은 병렬로
+
+const jobs = await claimJobs(BATCH_SIZE);
+
+// 임베딩 병렬 생성
+const embeddings = await Promise.all(
+  jobs.map(async (job) => {
+    const content = await getContent(job.itemKind, job.itemId);
+    return embedder.embed(content);
+  })
+);
+
+// LanceDB 순차 쓰기
+for (let i = 0; i < jobs.length; i++) {
+  await vectorStore.upsert({ id: jobs[i].itemId, vector: embeddings[i], ... });
+  await markDone(jobs[i].jobId);
+}
+```
+
+## 10. 참고 자료
+
+- **Memo.txt**: 섹션 8 - Vector Outbox + LanceDB writer 구현 지시
+- **현재 구현**: `src/core/vector-worker.ts`
+- **Transactional Outbox**: 마이크로서비스 패턴
+- **AXIOMMIND**: Principle 6 - 벡터 정합성