synapse-causal-memory 0.2.3 → 0.3.0

package/causal-memory.json

@@ -1,7 +1,7 @@
 {
   "version": "2.1.0",
-  "updatedAt": "2026-11-08T15:23:54.807Z",
-  "totalRules": 164,
+  "updatedAt": "2026-11-09T16:19:26.821Z",
+  "totalRules": 165,
   "totalRelations": 44,
   "rules": [
     {
@@ -4794,6 +4794,39 @@
         "Synapse Kit v0.2.3 3대 코어(compiler, memory, db) 통합 완료"
       ],
       "lastVerified": "2026-11-08"
+    },
+    {
+      "id": "ctx-active-session-snapshot",
+      "domain": "User_Preferences_And_Rules",
+      "title": "Active_Session_Context_Snapshot",
+      "entityType": "ContextCheckpoint",
+      "triggers": {
+        "alwaysActive": true,
+        "keywords": [
+          "context",
+          "checkpoint",
+          "resume",
+          "컨텍스트",
+          "이어서",
+          "default-session"
+        ]
+      },
+      "invariants": [
+        "[최근 작업 목표] core 영역의 기능을 확장하고 변경 사항을 무결하게 정합하는 작업",
+        "[다음 최우선 진행 과제] 추가/수정된 모듈에 대한 포괄적 통합 테스트 스위트 작성 및 회귀 방지"
+      ],
+      "actions": [
+        "추가/수정된 모듈에 대한 포괄적 통합 테스트 스위트 작성 및 회귀 방지",
+        "Bun 런타임 기반 빌드 검증 (`bun run build`) 및 무오류 확인",
+        "전역 컨텍스트 스냅샷 데이터베이스 동기화 및 기억 영속화"
+      ],
+      "context": [
+        "체크포인트 ID: ctx_20261110_005446_qw31 (세션: default-session, 시각: 2026-11-09T15:54:46.391Z)",
+        "제목: Synapse Kit v0.3.0 완료 - 6대 인지 슈퍼 코어 완비 및 31개 테스트 2022개 검증 100% 통과",
+        "완료 내역: 소스 코드 변경 및 모듈 구조 정비",
+        "핵심 결정: 하드코딩 배제 및 환경 변수/설정 모듈 중심의 설정 아키텍처 적용 | SOLID 단일 책임 원칙(SRP)을 준수한 독립 엔진 분리"
+      ],
+      "lastVerified": "2026-11-09"
     }
   ],
   "relations": [

package/dist/causal-branch.d.ts

@@ -0,0 +1,79 @@
+import { ContextCheckpointStore, type ContextCheckpoint } from './causal-context';
+import { CausalGraveyardStore } from './causal-graveyard';
+/**
+ * 컨텍스트 브랜치 레코드 규격
+ */
+export interface ContextBranch {
+    readonly name: string;
+    readonly baseCheckpointId: string;
+    readonly headCheckpointId: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly status: 'active' | 'merged' | 'abandoned';
+    readonly description?: string;
+    readonly mergedInto?: string;
+    readonly abandonmentReason?: string;
+}
+/**
+ * 브랜치 데이터베이스 규격
+ */
+export interface BranchDatabase {
+    readonly version: string;
+    readonly updatedAt: string;
+    readonly currentBranch: string;
+    readonly branches: readonly ContextBranch[];
+}
+/**
+ * 컨텍스트 브랜칭 및 머지 관리자 클래스 (SRP 준수)
+ */
+export declare class CausalBranchStore {
+    private readonly dbPath;
+    private readonly contextStore;
+    private readonly graveyardStore;
+    private database;
+    private lastMtimeMs;
+    constructor(customPathOrContextStore?: string | ContextCheckpointStore, contextStoreOrGraveyard?: any, graveyardStore?: CausalGraveyardStore);
+    private loadDatabase;
+    reloadIfNeeded(): void;
+    private saveDatabase;
+    /**
+     * 신규 브랜치 분기 (Fork)
+     */
+    createBranch(name: string, options?: {
+        baseId?: string;
+        description?: string;
+    }): Promise<ContextBranch>;
+    /**
+     * 활성 브랜치 전환 (Switch)
+     */
+    switchBranch(name: string): ContextBranch;
+    /**
+     * 브랜치 병합 (Merge)
+     * 소스 브랜치의 핵심 의사결정 및 완료 과업을 타깃 브랜치로 통합
+     */
+    mergeBranch(sourceName: string, targetName?: string): Promise<{
+        mergedBranch: ContextBranch;
+        resultingCheckpoint: ContextCheckpoint;
+    }>;
+    /**
+     * 실패한 브랜치 폐기 및 실패 원인 Graveyard 자동 흡수
+     */
+    abandonBranch(name: string, failureInfo?: string | {
+        failedApproach?: string;
+        errorSignature?: string;
+        rootCause?: string;
+        counterMeasure?: string;
+    }, safeAlternative?: string): {
+        branch: ContextBranch;
+        trapRecorded?: boolean;
+        success?: boolean;
+    };
+    /**
+     * 브랜치 목록 조회
+     */
+    listBranches(): ContextBranch[];
+    /**
+     * 현재 활성 브랜치 조회
+     */
+    getCurrentBranch(): ContextBranch;
+}

package/dist/causal-config.d.ts

@@ -25,4 +25,14 @@ export declare const CAUSAL_MEMORY_CONFIG: {
     readonly MCP_SERVER_NAME: "synapse-causal-memory";
     /** 공명 쿼리 시 컨텍스트 최대 노출 줄 수 (토큰 절감 임계치) */
     readonly MAX_CONTEXT_PREVIEW_LINES: number;
+    /** 전역 컨텍스트 스냅샷(Checkpoint) 저장소 기본 경로 */
+    readonly CONTEXT_DB_PATH: string;
+    /** 패키지 내장 폴백 컨텍스트 스냅샷 경로 */
+    readonly LOCAL_CONTEXT_DB_PATH: string;
+    /** 최대 보존 컨텍스트 체크포인트 개수 */
+    readonly MAX_CHECKPOINTS_RETAINED: number;
+    /** 옵시디언(Obsidian) 볼트 기본 연동 루트 경로 */
+    readonly DEFAULT_OBSIDIAN_VAULT_PATH: string;
+    /** 옵시디언 볼트 내부 인과율 렌즈 저장 서브디렉터리 */
+    readonly OBSIDIAN_LENS_SUBDIR: string;
 };

package/dist/causal-context.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 컨텍스트 스냅샷(Checkpoint) 단일 레코드 규격
+ */
+export interface ContextCheckpoint {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly title: string;
+    readonly createdAt: string;
+    readonly cwd: string;
+    readonly gitBranch?: string;
+    readonly gitCommit?: string;
+    readonly modifiedFiles: readonly string[];
+    readonly activeFiles: readonly string[];
+    readonly goal: string;
+    readonly completedSteps: readonly string[];
+    readonly pendingTasks: readonly string[];
+    readonly keyDecisions: readonly string[];
+    readonly activeInvariants: readonly string[];
+    readonly artifacts: readonly string[];
+    readonly customMeta?: Record<string, unknown>;
+}
+/**
+ * 컨텍스트 체크포인트 생성 입력 규격
+ */
+export interface SaveCheckpointInput {
+    readonly id?: string;
+    readonly sessionId?: string;
+    readonly title: string;
+    readonly cwd?: string;
+    readonly goal?: string;
+    readonly activeFiles?: readonly string[];
+    readonly modifiedFiles?: readonly string[];
+    readonly completedSteps?: readonly string[];
+    readonly pendingTasks?: readonly string[];
+    readonly keyDecisions?: readonly string[];
+    readonly activeInvariants?: readonly string[];
+    readonly artifacts?: readonly string[];
+    readonly keywords?: readonly string[];
+    readonly domain?: string;
+    readonly autoGit?: boolean;
+    readonly autoResonance?: boolean;
+    readonly customMeta?: Record<string, unknown>;
+}
+/**
+ * 컨텍스트 체크포인트 저장소 데이터베이스 규격
+ */
+export interface ContextCheckpointDatabase {
+    readonly version: string;
+    readonly updatedAt: string;
+    readonly latestCheckpointId: string | null;
+    readonly totalCheckpoints: number;
+    readonly checkpoints: readonly ContextCheckpoint[];
+}
+/**
+ * Git 현재 브랜치 및 최신 커밋 해시 자동 추출 헬퍼
+ */
+export declare function detectGitHeadInfo(cwd?: string): Promise<{
+    branch?: string;
+    commit?: string;
+}>;
+/**
+ * 세션 간 기억 손실 0%를 보장하는 인과율 컨텍스트 스냅샷 저장소 클래스 (SRP 준수)
+ */
+export declare class ContextCheckpointStore {
+    private readonly dbPath;
+    private readonly memoryDbPath?;
+    private database;
+    private lastMtimeMs;
+    constructor(customPath?: string, memoryDbPath?: string);
+    /**
+     * 디스크에서 체크포인트 데이터베이스 로드
+     */
+    private loadDatabase;
+    /**
+     * 외부 프로세스(CLI 또는 다른 에이전트)에 의해 파일이 갱신되었으면 자동 리로드
+     */
+    reloadIfNeeded(): void;
+    /**
+     * 원자적(Atomic) 파일 교체 방식으로 체크포인트 데이터베이스 영구 저장
+     */
+    private saveDatabase;
+    /**
+     * 고유 체크포인트 ID 생성
+     */
+    private static generateCheckpointId;
+    /**
+     * 현재 작업 컨텍스트를 스냅샷으로 박제하여 저장
+     */
+    saveCheckpoint(input: SaveCheckpointInput): Promise<ContextCheckpoint>;
+    /**
+     * 최신 체크포인트 조회 (특정 세션 지정 가능)
+     */
+    getLatestCheckpoint(sessionId?: string): ContextCheckpoint | null;
+    /**
+     * 특정 ID 또는 'latest' 키워드로 체크포인트 조회
+     */
+    getCheckpoint(idOrTag?: string, sessionId?: string): ContextCheckpoint | null;
+    /**
+     * 저장된 체크포인트 목록 조회
+     */
+    listCheckpoints(options?: {
+        sessionId?: string;
+        limit?: number;
+    }): ContextCheckpoint[];
+    /**
+     * 특정 체크포인트 삭제
+     */
+    deleteCheckpoint(id: string): boolean;
+    /**
+     * 새 채팅창/에이전트 세션에서 0ms 만에 맥락을 100% 복원하기 위한 초고밀도 프롬프트 포맷터
+     */
+    static formatForAgentResume(checkpoint: ContextCheckpoint, compact?: boolean): string;
+}

package/dist/causal-graveyard.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 실패 가설 및 함정(Trap) 레코드 규격 (Negative Knowledge)
+ */
+export interface FailureHypothesis {
+    readonly id: string;
+    readonly title: string;
+    readonly failedApproach: string;
+    readonly errorSignature?: string;
+    readonly rootCause: string;
+    readonly counterMeasure: string;
+    readonly triggerKeywords: readonly string[];
+    readonly triggerFiles?: readonly string[];
+    readonly environment?: string;
+    readonly hitCount?: number;
+    readonly createdAt: string;
+    readonly lastEncounteredAt?: string;
+    readonly trapPattern?: string;
+    readonly domain?: string;
+    readonly severity?: string;
+    readonly reason?: string;
+    readonly safeAlternative?: string;
+    readonly avoidFiles?: readonly string[];
+}
+/**
+ * 지뢰(Trap) 사전 탐지 결과 규격
+ */
+export interface TrapWarning {
+    readonly trapId: string;
+    readonly title: string;
+    readonly riskLevel: 'CRITICAL' | 'WARNING' | 'NOTICE';
+    readonly matchedBy: 'keyword' | 'file' | 'error_signature';
+    readonly matchedPattern: string;
+    readonly whyItFails: string;
+    readonly recommendedFix: string;
+}
+export type TrapScanResult = TrapWarning[] & {
+    readonly trapped: boolean;
+    readonly triggeredTraps: readonly TrapWarning[];
+    readonly highestSeverity: 'CRITICAL' | 'WARNING' | 'NOTICE' | 'NONE';
+};
+/**
+ * 실패 가설 묘지 데이터베이스 규격
+ */
+export interface GraveyardDatabase {
+    readonly version: string;
+    readonly updatedAt: string;
+    readonly totalTraps: number;
+    readonly traps: readonly FailureHypothesis[];
+}
+/**
+ * 실패 가설 묘지(Negative Memory) 관리 및 지뢰 사전 탐지 엔진 클래스 (SRP 준수)
+ */
+export declare class CausalGraveyardStore {
+    private readonly dbPath;
+    private database;
+    private lastMtimeMs;
+    constructor(customPathOrMemoryStore?: string | unknown);
+    private loadDatabase;
+    reloadIfNeeded(): void;
+    private saveDatabase;
+    /**
+     * 신규 실패 가설(Trap) 등록 또는 갱신
+     */
+    assertTrap(input: any): FailureHypothesis;
+    /**
+     * 작업 컨텍스트(코드, 명령어, 파일, 텍스트)에서 이미 실패했던 지뢰(Trap)가 있는지 사전 스캔
+     */
+    scanTraps(query: {
+        text?: string;
+        code?: string;
+        files?: readonly string[];
+        keywords?: readonly string[];
+    }): TrapScanResult;
+    /**
+     * 저장된 모든 실패 가설 목록 조회
+     */
+    listTraps(): FailureHypothesis[];
+    /**
+     * 하위 호환 alias
+     */
+    getAllTraps(): FailureHypothesis[];
+    /**
+     * 특정 실패 가설 삭제
+     */
+    deleteTrap(id: string): boolean;
+    /**
+     * 지뢰 경고 프롬프트 포맷터
+     */
+    static formatWarningsForAgent(warnings: readonly TrapWarning[]): string;
+    /**
+     * 하위 호환 alias
+     */
+    static formatTrapWarnings(warnings: any): string;
+}

package/dist/causal-lens.d.ts

@@ -0,0 +1,133 @@
+import { CausalMemoryStore } from './causal-store';
+import { ContextCheckpointStore } from './causal-context';
+import { CausalGraveyardStore } from './causal-graveyard';
+import { CausalTimeSeriesEngine } from './causal-timeseries';
+/**
+ * 렌즈 내보내기 결과 보고서 규격
+ */
+export interface LensExportResult {
+    readonly success: boolean;
+    readonly vaultPath: string;
+    readonly exportedRules: number;
+    readonly exportedGraveyard: number;
+    readonly exportedCheckpoints: number;
+    readonly canvasGenerated: boolean;
+    readonly timelineGenerated: boolean;
+    readonly durationMs: number;
+    readonly error?: string;
+}
+/**
+ * 렌즈 가져오기 결과 보고서 규격
+ */
+export interface LensImportResult {
+    readonly success: boolean;
+    readonly vaultPath: string;
+    readonly importedRules: number;
+    readonly importedGraveyard: number;
+    readonly durationMs: number;
+    readonly error?: string;
+}
+/**
+ * 양방향 동기화 결과 보고서 규격
+ */
+export interface LensSyncResult {
+    readonly success: boolean;
+    readonly exportResult: LensExportResult;
+    readonly importResult: LensImportResult;
+    readonly syncedAt: string;
+}
+/**
+ * 옵시디언 캔버스 노드 규격
+ */
+export interface ObsidianCanvasNode {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly type: 'text' | 'file';
+    readonly text?: string;
+    readonly file?: string;
+    readonly color?: string;
+}
+/**
+ * 옵시디언 캔버스 엣지(간선) 규격
+ */
+export interface ObsidianCanvasEdge {
+    readonly id: string;
+    readonly fromNode: string;
+    readonly fromSide: 'top' | 'right' | 'bottom' | 'left';
+    readonly toNode: string;
+    readonly toSide: 'top' | 'right' | 'bottom' | 'left';
+    readonly label?: string;
+    readonly color?: string;
+}
+/**
+ * 옵시디언 캔버스 문서 규격 (.canvas)
+ */
+export interface ObsidianCanvasDocument {
+    readonly nodes: readonly ObsidianCanvasNode[];
+    readonly edges: readonly ObsidianCanvasEdge[];
+}
+/**
+ * 옵시디언(Obsidian) 지식 베이스와 인과율 메모리를 양방향 연동하는 렌즈 엔진 클래스 (SRP 준수)
+ */
+export declare class CausalObsidianLensEngine {
+    private readonly memoryStore;
+    private readonly contextStore;
+    private readonly graveyardStore;
+    private readonly timeSeriesEngine;
+    constructor(memoryStore?: CausalMemoryStore, contextStore?: ContextCheckpointStore, graveyardStore?: CausalGraveyardStore, timeSeriesEngine?: CausalTimeSeriesEngine);
+    /**
+     * 지정된 옵시디언 볼트 경로로 인과율 메모리 전체(규칙, 함정, 스냅샷, 타임라인, 캔버스)를 마크다운으로 내보내기
+     */
+    exportToVault(vaultRoot?: string): Promise<LensExportResult>;
+    /**
+     * 옵시디언 볼트의 마크다운 파일들을 스캔하여 인과율 규칙 및 함정 데이터로 역가져오기 (Import)
+     */
+    importFromVault(vaultRoot?: string): Promise<LensImportResult>;
+    /**
+     * 볼트와의 양방향 동기화 (최신성 기반 안전한 병합)
+     */
+    syncWithVault(vaultRoot?: string): Promise<LensSyncResult>;
+    /**
+     * 단일 CausalRule을 Obsidian 마크다운으로 변환
+     */
+    private renderRuleToMarkdown;
+    /**
+     * 단일 FailureHypothesis(함정)를 Obsidian 마크다운으로 변환
+     */
+    private renderTrapToMarkdown;
+    /**
+     * 단일 컨텍스트 체크포인트를 Obsidian 마크다운으로 변환
+     */
+    private renderCheckpointToMarkdown;
+    /**
+     * 타임라인 마크다운 렌더링
+     */
+    private renderTimelineMarkdown;
+    /**
+     * 옵시디언 캔버스(Canvas) JSON 문서 생성
+     */
+    private generateCanvasDocument;
+    /**
+     * 도메인별 캔버스 색상 코드 매핑 (1: 빨강, 2: 주황, 3: 노랑, 4: 초록, 5: 파랑, 6: 보라)
+     */
+    private getColorForDomain;
+    /**
+     * 마크다운 텍스트로부터 CausalRule 역파싱
+     */
+    private parseRuleMarkdown;
+    /**
+     * 마크다운 텍스트로부터 FailureHypothesis(함정) 역파싱
+     */
+    private parseTrapMarkdown;
+    /**
+     * 원자적 파일 쓰기 (임시 파일 생성 후 renameSync로 덮어쓰기하여 정전/중단 시 손상 0% 보장)
+     */
+    private atomicWriteFile;
+    /**
+     * 파일명에 사용할 수 없는 특수문자 및 Path Traversal 시퀀스 제거
+     */
+    private sanitizeFileName;
+}

package/dist/causal-predictor.d.ts

@@ -0,0 +1,42 @@
+import { CausalMemoryStore } from './causal-store';
+import { ContextCheckpointStore } from './causal-context';
+/**
+ * 연쇄 파급 영향 노드 규격
+ */
+export interface AffectedNode {
+    readonly name: string;
+    readonly domain: string;
+    readonly hopLevel: number;
+    readonly relationType: string;
+    readonly riskScore: number;
+    readonly riskReason: string;
+    readonly requiredInvariants: readonly string[];
+}
+/**
+ * 인과 연쇄 폭발 반경(Blast Radius) 분석 보고서 규격
+ */
+export interface BlastRadiusReport {
+    readonly triggerFiles: readonly string[];
+    readonly overallRisk: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+    readonly maxRiskScore: number;
+    readonly affectedNodes: readonly AffectedNode[];
+    readonly prefetchedInvariants: readonly string[];
+    readonly suggestedTargetFiles: readonly string[];
+    readonly durationMs: number;
+}
+/**
+ * 인과 연쇄 파급 예측 및 Blast Radius 분석 엔진 클래스 (SRP 준수)
+ */
+export declare class CausalPredictorEngine {
+    private readonly memoryStore;
+    private readonly contextStore;
+    constructor(memoryStore?: CausalMemoryStore, contextStore?: ContextCheckpointStore);
+    /**
+     * 파일 수정 시 2~3단계 뒤에 발생할 연쇄 파급 반경 계산
+     */
+    analyzeBlastRadius(files: readonly string[], maxHops?: number): BlastRadiusReport;
+    /**
+     * 예측 보고서 마크다운 포맷터
+     */
+    static formatPredictReport(report: BlastRadiusReport): string;
+}