/**
 * 관계 그래프 서비스
 * 기억 간의 관계를 저장하고 관리하는 서비스
 *
 * 주요 기능:
 * - 관계 추가/삭제/조회
 * - 순환 참조 감지 (DFS)
 * - N-hop 관계 탐색 (BFS)
 * - 신뢰도 갱신
 * - 캐싱 계층 (L1: MemoryCache 10분, L2: PersistentCache 7일)
 * - 배치 삽입 최적화
 */
import Database from 'better-sqlite3';
import type { ICacheService } from '../../../shared/interfaces/cache.interface.js';
import type { AddRelationOptions, GetRelatedMemoriesOptions, GetRelationsOptions, IRelationGraph, MemoryRelation, RelationMetadata } from '../../../shared/types/relation-graph.js';
import type { RelationType } from '../../../shared/types/relation.js';
/**
 * 관계 그래프 서비스
 */
export declare class RelationGraph implements IRelationGraph {
    private db;
    private l1Cache;
    private l2Cache;
    private cacheKeyIndex;
    constructor(db: Database.Database, l1Cache: ICacheService<MemoryRelation[]>, l2Cache: ICacheService<MemoryRelation[]>);
    /**
     * 관계 추가
     * UNIQUE 제약 검증 및 순환 참조 감지를 수행합니다.
     *
     * 트랜잭션 내에서 실행하여 순환 참조 감지와 관계 추가를 원자적으로 처리합니다.
     * 이를 통해 경쟁 조건을 방지하고 일관성을 보장합니다.
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param options 추가 옵션
     * @returns 추가된 관계 ID
     */
    addRelation(sourceId: string, targetId: string, relationType: RelationType, options?: AddRelationOptions): Promise<number>;
    /**
     * 관계 추가 내부 로직
     * 기존 관계 확인 및 새 관계 추가를 수행합니다.
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param confidence 신뢰도
     * @param metadata 메타데이터
     * @param metadataJson 메타데이터 JSON 문자열
     * @param updateOnConflict 충돌 시 업데이트 여부
     * @param allowCyclic 순환 참조 허용 여부
     * @returns 관계 ID
     */
    private addRelationInternal;
    /**
     * 관계 추가 에러 처리
     * 동시성 문제로 인한 UNIQUE constraint 에러를 처리합니다.
     *
     * @param error 발생한 에러
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param confidence 신뢰도
     * @param metadata 메타데이터
     * @param updateOnConflict 충돌 시 업데이트 여부
     * @returns 관계 ID 또는 에러를 throw
     */
    private handleRelationAddError;
    /**
     * 관계 입력 검증
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     */
    private validateRelationInput;
    /**
     * 순환 참조 확인
     * 트랜잭션 내에서 호출되는 경우 중첩 트랜잭션을 방지합니다.
     * 트랜잭션 상태를 확인합니다.
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     */
    private checkForCyclicRelation;
    /**
     * 메타데이터 준비
     *
     * @param options 추가 옵션
     * @param allowCyclic 순환 참조 허용 여부
     * @returns 준비된 메타데이터
     */
    private prepareMetadata;
    /**
     * 기존 관계 조회
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @returns 기존 관계 정보 또는 null
     */
    private findExistingRelation;
    /**
     * 기존 관계 처리
     *
     * @param existing 기존 관계 정보
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param confidence 신뢰도
     * @param metadata 메타데이터
     * @param updateOnConflict 충돌 시 업데이트 여부
     * @returns 관계 ID
     */
    private handleExistingRelation;
    /**
     * 새 관계 추가
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param confidence 신뢰도
     * @param metadataJson 메타데이터 JSON 문자열
     * @param allowCyclic 순환 참조 허용 여부
     * @returns 추가된 관계 ID
     */
    private insertNewRelation;
    /**
     * 순환 참조 플래그 업데이트
     *
     * @param relationId 관계 ID
     */
    private updateCyclicFlag;
    /**
     * 관계 조회
     *
     * @param memoryId 기억 ID
     * @param options 조회 옵션
     * @returns 관계 목록
     */
    getRelations(memoryId: string, options?: GetRelationsOptions): Promise<MemoryRelation[]>;
    /**
     * 여러 메모리에 대한 관계 일괄 조회 (N+1 완화)
     * @param memoryIds 기억 ID 목록
     * @param options 조회 옵션 (getRelations와 동일)
     * @returns memoryId -> MemoryRelation[] 맵 (캐시 미사용)
     */
    getRelationsBatch(memoryIds: string[], options?: GetRelationsOptions): Promise<Map<string, MemoryRelation[]>>;
    /**
     * 관련 기억 조회 (N-hop 관계 탐색)
     * BFS 알고리즘을 사용하여 N-hop 관계를 탐색합니다.
     *
     * @param memoryId 시작 기억 ID
     * @param options 탐색 옵션
     * @returns 관련 기억 ID 목록과 hop 거리
     */
    getRelatedMemories(memoryId: string, options?: GetRelatedMemoriesOptions): Promise<Array<{
        memory_id: string;
        hop_distance: number;
        relation_path: Array<{
            source_id: string;
            target_id: string;
            relation_type: RelationType;
        }>;
    }>>;
    /**
     * 관계 삭제
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @returns 삭제 성공 여부
     */
    removeRelation(sourceId: string, targetId: string, relationType: RelationType): Promise<boolean>;
    /**
     * 신뢰도 갱신
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param newConfidence 새로운 신뢰도
     * @param reason 갱신 이유
     * @returns 갱신 성공 여부
     */
    updateConfidence(sourceId: string, targetId: string, relationType: RelationType, newConfidence: number, reason?: string): Promise<boolean>;
    /**
     * 순환 참조 감지 (DFS)
     *
     * 트랜잭션 내에서 실행하여 경쟁 조건을 방지합니다.
     * 순환 참조 감지 중에 다른 프로세스/스레드에서 관계가 추가되는 것을 방지합니다.
     * 트랜잭션 격리 수준을 사용합니다.
     *
     * 성능 최적화:
     * - 최대 탐색 깊이 제한 (기본값: 10)
     * - 대규모 그래프에서 무한 루프 방지
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param maxDepth 최대 탐색 깊이 (기본값: 10)
     * @returns 순환 참조 여부
     */
    /**
     * 순환 참조 감지 내부 로직 (트랜잭션 없이 실행)
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param maxDepth 최대 탐색 깊이
     * @returns 순환 참조 여부
     */
    private detectCycleInternal;
    /**
     * 순환 참조 감지 (공개 메서드)
     * 트랜잭션을 자동으로 관리합니다.
     *
     * @param sourceId 소스 기억 ID
     * @param targetId 타겟 기억 ID
     * @param relationType 관계 유형
     * @param maxDepth 최대 탐색 깊이 (기본값: 10)
     * @returns 순환 참조 여부
     */
    detectCycle(sourceId: string, targetId: string, relationType: RelationType, maxDepth?: number): Promise<boolean>;
    /**
     * 캐시 키 생성
     * 공통 유틸리티를 사용하여 일관된 캐시 키를 생성합니다.
     *
     * @param memoryId 기억 ID
     * @param options 조회 옵션
     * @returns 캐시 키
     */
    private generateCacheKey;
    /**
     * 캐시 키를 인덱스에 추가
     * 정확한 캐시 무효화를 위해 사용
     *
     * @param memoryId 기억 ID
     * @param cacheKey 캐시 키
     */
    private addCacheKeyToIndex;
    /**
     * 캐시 무효화
     * 특정 메모리 ID와 관련된 캐시를 정확하게 무효화합니다.
     *
     * 최적화 전략:
     * 1. 캐시 키 인덱스를 우선 사용하여 O(1) 접근으로 정확한 캐시 키 삭제
     * 2. 인덱스가 없는 경우에만 패턴 기반 삭제 수행 (fallback)
     *
     * 성능 고려사항:
     * - 인덱스가 있는 경우: O(n) where n = 해당 memoryId의 캐시 키 수
     * - 인덱스가 없는 경우: O(m) where m = 전체 캐시 키 수 (최악의 경우)
     * - 일반적으로 인덱스가 있으므로 효율적
     *
     * @param memoryId 기억 ID
     */
    private invalidateCache;
    /**
     * 배치 관계 추가
     * 여러 관계를 한 번에 추가하여 성능을 최적화합니다.
     *
     * @param relations 추가할 관계 목록
     * @returns 배치 처리 결과 (성공한 관계 ID 목록 및 실패한 관계 정보)
     */
    addRelationsBatch(relations: Array<{
        source_id: string;
        target_id: string;
        relation_type: RelationType;
        confidence?: number;
        metadata?: RelationMetadata;
    }>): Promise<{
        insertedIds: number[];
        failed: Array<{
            source_id: string;
            target_id: string;
            relation_type: RelationType;
            error: string;
        }>;
        total: number;
        success: number;
        failedCount: number;
    }>;
}
//# sourceMappingURL=relation-graph.d.ts.map