synapse-db 0.3.0 → 0.3.1

package/dist/serializer.d.ts

@@ -7,8 +7,13 @@ export interface RawParsedMarkdown<T = Record<string, any>> {
 }
 /**
  * 텍스트에서 옵시디언 위키링크([[target|alias]] 또는 [[target]]) 자동 추출
+ * 초고속 Zero-Regex 인덱스 스캐너: 정규식 엔진 생성/컴파일/exec 배열 할당 없이 indexOf 슬라이싱으로 추출
  */
 export declare function extractWikilinks(text: string, defaultCollection?: string): SynapseWikilink[];
+/**
+ * 직렬화/파싱 왕복 없이 메모리 객체(data)와 본문(body)에서 직접 위키링크를 초고속 추출
+ */
+export declare function extractWikilinksFromDataAndBody(data: Record<string, any> | undefined | null, body: string, defaultCollection?: string): SynapseWikilink[];
 /**
  * YAML Frontmatter 안전 파서 (순수 TypeScript 무손실 복원)
  */

package/dist/types.d.ts

@@ -2,6 +2,7 @@
  * 범용 마크다운 시냅스 데이터베이스 타입 규격 (Synapse-DB Type Specifications)
  * SOLID 원칙 준수: 단일 책임 원칙(SRP)에 따른 타입 정의 분리
  */
+import type { CausalWalConfig } from "./wal/config";
 /** 시냅스 위키링크 규격 ([[collection/id|alias]]) */
 export interface SynapseWikilink {
     readonly raw: string;
@@ -52,6 +53,7 @@ export interface SynapseDBConfig {
     readonly vaultDir: string;
     readonly autoWatch?: boolean;
     readonly persistDebounceMs?: number;
+    readonly wal?: CausalWalConfig;
 }
 /** 시냅스 데이터베이스 전체 통계 요약 */
 export interface SynapseDBStats {

package/dist/wal/arena.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 러스트 Bumpalo 스타일 지역 아레나 할당기 및 트랜잭션 스코프 (Arena Transaction Lifecycle)
+ * - 트랜잭션 중 발생하는 모든 변경 슬롯을 사전 할당된 연속 풀(Pool)에서 포인터 전진(cursor++)만으로 O(1) 할당
+ * - 커밋(Commit) 또는 롤백(Rollback) 즉시 포인터를 0으로 리셋하여 0ns 일괄 해제 (Zero-GC)
+ */
+import type { SynapseDocument } from "../types";
+import { CausalWalEventType, type CompilerTemporalMetric } from "./config";
+/** 아레나 내부에서 재사용되는 가변 슬롯 구조체 */
+export interface ArenaMutationSlot {
+    eventType: CausalWalEventType;
+    collection: string;
+    docId: string;
+    prevDoc: SynapseDocument | null;
+    nextDoc: SynapseDocument | null;
+    edgesAdded: string[];
+    edgesRemoved: string[];
+    rawMarkdown: string | null;
+    targetDiskPath: string | null;
+    compilerMetric?: CompilerTemporalMetric;
+}
+/** 아레나 메모리 통계 */
+export interface ArenaStats {
+    readonly poolCapacity: number;
+    readonly activeCursor: number;
+    readonly totalTransactionsCommitted: number;
+    readonly totalTransactionsRolledBack: number;
+    readonly totalSlotReuses: number;
+}
+export declare class CausalArenaAllocator {
+    private readonly pool;
+    private cursor;
+    private inTransaction;
+    private totalCommitted;
+    private totalRolledBack;
+    private totalSlotReuses;
+    constructor(initialCapacity?: number);
+    private createEmptySlot;
+    /**
+     * 트랜잭션 아레나 스코프 시작
+     */
+    beginScope(): void;
+    /**
+     * 현재 트랜잭션 스코프 활성화 여부
+     */
+    isScopeActive(): boolean;
+    /**
+     * 포인터 전진(Bump Allocation)을 통해 힙 할당 없이 슬롯 획득
+     */
+    allocSlot(eventType: CausalWalEventType, collection: string, docId: string, prevDoc: SynapseDocument | null, nextDoc: SynapseDocument | null, edgesAdded: string[], edgesRemoved: string[], rawMarkdown?: string | null, targetDiskPath?: string | null, compilerMetric?: CompilerTemporalMetric): ArenaMutationSlot;
+    /**
+     * 현재 스코프에 적재된 유효 슬롯 뷰 반환
+     */
+    getActiveSlots(): readonly ArenaMutationSlot[];
+    /**
+     * 커밋 완료 후 O(1) 포인터 리셋 (0ns Instant Deallocation)
+     */
+    commitAndReset(): void;
+    /**
+     * 예외 발생 시 롤백 및 O(1) 포인터 리셋 (커넥톰 및 WAL 오염 0%)
+     */
+    rollbackAndReset(): void;
+    /**
+     * 사용된 슬롯의 내부 참조만 즉시 비워 메모리 누수 차단 (슬롯 객체 자체는 풀에 보존)
+     */
+    private clearReferencesUpToCursor;
+    /**
+     * 아레나 할당기 통계 조회
+     */
+    getStats(): ArenaStats;
+}

package/dist/wal/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 시냅스 Causal-WAL 엔진 환경 설정 및 상수 모듈 (WAL Configuration & Constants)
+ * 하드코딩 배제 원칙 준수: 모든 기본 용량, 타임아웃, PRAGMA 상수를 중앙 집중 관리
+ */
+export declare const WAL_CONFIG_DEFAULTS: {
+    /** 순환 링 버퍼 기본 슬롯 용량 (2의 거듭제곱 권장) */
+    readonly RING_BUFFER_CAPACITY: number;
+    /** 트랜잭션 아레나 초기 사전 할당 슬롯 수 */
+    readonly ARENA_INITIAL_CAPACITY: number;
+    /** 아레나 최대 확장 상한선 */
+    readonly ARENA_MAX_CAPACITY: number;
+    /** SQLite WAL 기본 파일명 */
+    readonly SQLITE_WAL_FILENAME: string;
+    /** SQLite mmap 가상 메모리 매핑 크기 (256MB - OS 페이지 캐시 제로-카피 위임) */
+    readonly SQLITE_MMAP_SIZE_BYTES: number;
+    /** SQLite Busy Timeout (밀리초) */
+    readonly SQLITE_BUSY_TIMEOUT_MS: number;
+    /** SQLite WAL 동기화 모드 */
+    readonly SQLITE_SYNC_MODE: "NORMAL" | "FULL" | "OFF";
+};
+/** 인과율 WAL 이벤트 유형 */
+export declare enum CausalWalEventType {
+    DOC_UPSERT = "DOC_UPSERT",
+    DOC_DELETE = "DOC_DELETE",
+    EDGE_LINK = "EDGE_LINK",
+    EDGE_UNLINK = "EDGE_UNLINK",
+    COMPILER_METRIC = "COMPILER_METRIC",
+    CHECKPOINT_MARK = "CHECKPOINT_MARK"
+}
+/** 컴파일러 시계열 메트릭 페이로드 규격 */
+export interface CompilerTemporalMetric {
+    readonly targetFile: string;
+    readonly language: string;
+    readonly durationMs: number;
+    readonly binarySizeBytes?: number;
+    readonly symbolCount?: number;
+    readonly success: boolean;
+    readonly errorMessage?: string;
+}
+/** WAL 설정 옵션 인터페이스 */
+export interface CausalWalConfig {
+    /** 인메모리 링 버퍼 최대 슬롯 수 (기본: 4096) */
+    readonly ringCapacity?: number;
+    /** 아레나 사전 할당 슬롯 수 (기본: 256) */
+    readonly arenaCapacity?: number;
+    /** SQLite WAL 디스크 영속화 활성화 여부 (기본: false - 순수 인메모리 링 버퍼) */
+    readonly persistSqlite?: boolean;
+    /** SQLite WAL 파일 커스텀 경로 (미지정 시 vaultDir 내부에 생성) */
+    readonly sqlitePath?: string;
+    /** SQLite 동기화 수준 */
+    readonly syncMode?: "NORMAL" | "FULL" | "OFF";
+}

package/dist/wal/index.d.ts

@@ -0,0 +1,81 @@
+import { SynapseConnectome } from "../connectome";
+import type { SynapseDocument } from "../types";
+import { type CausalWalConfig, type CompilerTemporalMetric } from "./config";
+import { TemporalRingBuffer, type CausalWalEntry, type RingBufferStats } from "./ringBuffer";
+import { CausalArenaAllocator, type ArenaMutationSlot, type ArenaStats } from "./arena";
+import { SqliteCausalWalStore } from "./sqliteWalStore";
+import { type CausalTimelineDiff } from "./timeTravel";
+export interface CausalWalUnifiedStats {
+    readonly ringBuffer: RingBufferStats;
+    readonly arena: ArenaStats;
+    readonly sqlite: {
+        readonly enabled: boolean;
+        readonly dbPath: string | null;
+        readonly journalMode: string;
+        readonly lastFlushedLsn: number;
+        readonly persistedCount: number;
+    };
+}
+export declare class CausalWalEngine {
+    readonly ringBuffer: TemporalRingBuffer;
+    readonly arena: CausalArenaAllocator;
+    readonly sqliteStore: SqliteCausalWalStore | null;
+    constructor(vaultDir: string, config?: CausalWalConfig);
+    /**
+     * SQLite WAL 스토어 초기화 및 기존 WAL 로그로부터 크래시 복구 수행
+     */
+    initAndRecover(connectome: SynapseConnectome): number;
+    /**
+     * 이전 문서와 신규 문서 간의 위키링크 시냅스 간선 차분(Added / Removed) 계산
+     * Zero-Allocation Fast-Path: 위키링크가 없거나 단일 링크가 동일한 경우 Set/배열 할당 완전 생략
+     */
+    static computeEdgeDiff(prevDoc: SynapseDocument | null, nextDoc: SynapseDocument | null): {
+        edgesAdded: string[];
+        edgesRemoved: string[];
+    };
+    /**
+     * 문서 생성/수정 이벤트를 WAL에 기록 (트랜잭션 중이면 아레나에 스테이징, 아니면 즉시 커밋)
+     */
+    recordDocumentUpsert(prevDoc: SynapseDocument | null, nextDoc: SynapseDocument, rawMarkdown?: string | null, targetDiskPath?: string | null, timestampMs?: number): CausalWalEntry | null;
+    /**
+     * 문서 삭제 이벤트를 WAL에 기록
+     */
+    recordDocumentDelete(prevDoc: SynapseDocument, targetDiskPath?: string | null, timestampMs?: number): CausalWalEntry | null;
+    /**
+     * 컴파일러 빌드 지연시간 및 바이너리 크기 시계열 메트릭을 WAL에 기록
+     */
+    recordCompilerMetric(metric: CompilerTemporalMetric, timestampMs?: number): CausalWalEntry;
+    /**
+     * 아레나 기반 원자적 트랜잭션 실행 (예외 발생 시 0ns 롤백, 성공 시 일괄 커밋)
+     */
+    executeArenaTransaction<TResult>(fn: () => TResult, onCommitSlot: (slot: ArenaMutationSlot) => void): TResult;
+    /**
+     * 아레나 기반 비동기 원자적 트랜잭션 실행 (async 콜백 내 save/delete 완벽 지원)
+     */
+    executeArenaTransactionAsync<TResult>(fn: () => Promise<TResult> | TResult, onCommitSlot: (slot: ArenaMutationSlot) => void): Promise<TResult>;
+    /**
+     * 특정 LSN 시점의 시냅스 커넥톰 즉시 복원 (Time-Travel)
+     */
+    asOfLsn(connectome: SynapseConnectome, targetLsn: number): SynapseConnectome;
+    /**
+     * 특정 타임스탬프 시점의 시냅스 커넥톰 즉시 복원 (Time-Travel)
+     */
+    asOf(connectome: SynapseConnectome, timestampMsOrIso: number | string): SynapseConnectome;
+    /**
+     * 두 LSN 시점 간의 인과율 차분(Diff) 조회
+     */
+    diffBetweenLsn(fromLsn: number, toLsn: number): CausalTimelineDiff;
+    /**
+     * 통합 WAL 통계 조회
+     */
+    getStats(): CausalWalUnifiedStats;
+    /**
+     * SQLite WAL 스토어 안전 종료
+     */
+    close(): void;
+}
+export * from "./config";
+export * from "./ringBuffer";
+export * from "./arena";
+export * from "./sqliteWalStore";
+export * from "./timeTravel";

package/dist/wal/ringBuffer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 러스트 메모리 철학 기반 순환 링 버퍼 WAL (Zero-GC Temporal Ring Buffer)
+ * - 고정 용량 슬롯 배열 및 TypedArray(Float64Array) 인덱스 사전 할당
+ * - 용량 초과 시 가비지 컬렉터(GC) 개입 없이 가장 오래된 슬롯을 O(1)로 덮어쓰기(FIFO Drop)
+ * - LSN(Log Sequence Number) 및 타임스탬프 기반 초고속 시계열 탐색 지원
+ */
+import type { SynapseDocument } from "../types";
+import { CausalWalEventType, type CompilerTemporalMetric } from "./config";
+/** 단일 인과율 WAL 로그 엔트리 (구조적 공유를 위한 불변 참조 유지) */
+export interface CausalWalEntry<TData = any> {
+    readonly lsn: number;
+    readonly timestampMs: number;
+    readonly eventType: CausalWalEventType;
+    readonly collection: string;
+    readonly docId: string;
+    /** 변경 전 문서 상태 참조 (Time-Travel 역방향 복원용, 신규 생성 시 null) */
+    readonly prevDoc: SynapseDocument<TData> | null;
+    /** 변경 후 문서 상태 참조 (삭제 시 null) */
+    readonly nextDoc: SynapseDocument<TData> | null;
+    /** 이번 이벤트로 새로 연결된 위키링크 시냅스 타겟 노드 목록 */
+    readonly edgesAdded: readonly string[];
+    /** 이번 이벤트로 단절된 위키링크 시냅스 타겟 노드 목록 */
+    readonly edgesRemoved: readonly string[];
+    /** 컴파일러 시계열 메트릭 (COMPILER_METRIC 이벤트 전용) */
+    readonly compilerMetric?: CompilerTemporalMetric;
+}
+/** 링 버퍼 상태 통계 */
+export interface RingBufferStats {
+    readonly capacity: number;
+    readonly size: number;
+    readonly currentLsn: number;
+    readonly oldestLsn: number;
+    readonly overwrittenCount: number;
+    readonly utilizationRatio: number;
+}
+export declare class TemporalRingBuffer {
+    readonly capacity: number;
+    private readonly isPowerOfTwo;
+    private readonly bitMask;
+    private readonly slots;
+    private readonly lsnBuffer;
+    private readonly tsBuffer;
+    private head;
+    private tail;
+    private count;
+    private nextLsn;
+    private overwrittenCount;
+    constructor(capacity?: number);
+    private wrapIndex;
+    /**
+     * 새로운 WAL 이벤트를 링 버퍼에 O(1)로 기록 (용량 초과 시 자동 FIFO 덮어쓰기)
+     */
+    append(entryInput: Omit<CausalWalEntry, "lsn" | "timestampMs"> & {
+        timestampMs?: number;
+    }): CausalWalEntry;
+    /**
+     * 외부(SQLite WAL 복구 등)에서 이미 LSN이 부여된 엔트리를 링 버퍼에 적재
+     */
+    appendRecovered(entry: CausalWalEntry): void;
+    private writeRawEntry;
+    /**
+     * LSN 번호로 O(1) 직접 슬롯 계산 조회
+     */
+    getByLsn(targetLsn: number): CausalWalEntry | null;
+    /**
+     * 최신 엔트리부터 역순(최신 ➔ 과거)으로 순회하며 콜백 실행 (Time-Travel 역방향 리플레이 전용)
+     * 콜백이 false를 반환하면 즉시 순회 중단
+     */
+    forEachReverse(visitor: (entry: CausalWalEntry) => boolean | void): void;
+    /**
+     * 오래된 엔트리부터 시간순(과거 ➔ 최신)으로 전체 엔트리 배열 반환
+     */
+    toArray(): CausalWalEntry[];
+    /**
+     * 특정 LSN 이후의 엔트리들만 시간순 반환 (증분 SQLite 플러시 및 Diff 계산용)
+     */
+    getEntriesSinceLsn(afterLsn: number): CausalWalEntry[];
+    /**
+     * 현재 최신 LSN 번호 반환 (기록된 엔트리가 없으면 0)
+     */
+    getCurrentLsn(): number;
+    /**
+     * 링 버퍼에 남아 있는 가장 오래된 LSN 번호 반환
+     */
+    getOldestLsn(): number;
+    /**
+     * 링 버퍼 실시간 통계 반환
+     */
+    getStats(): RingBufferStats;
+    /**
+     * 링 버퍼 전체 슬롯 O(1) 리셋
+     */
+    clear(): void;
+}

package/dist/wal/sqliteWalStore.d.ts

@@ -0,0 +1,38 @@
+import type { CausalWalEntry } from "./ringBuffer";
+export declare class SqliteCausalWalStore {
+    private readonly syncMode;
+    readonly dbPath: string;
+    private sqlite;
+    private insertStmt;
+    private batchTx;
+    private lastFlushedLsn;
+    constructor(dbPath: string, syncMode?: "NORMAL" | "FULL" | "OFF");
+    /**
+     * SQLite 데이터베이스 초기화 및 WAL / mmap PRAGMA 활성화
+     */
+    init(): void;
+    /**
+     * WAL 엔트리 배치를 사전 컴파일된 단일 원자적 트랜잭션으로 SQLite WAL에 영속화
+     */
+    flushEntries(entries: readonly CausalWalEntry[]): number;
+    /**
+     * 디스크에 영속화된 전체 WAL 엔트리 로드 (크래시 복구 및 링 버퍼 재구성용)
+     */
+    loadAllEntries(): CausalWalEntry[];
+    /**
+     * 현재 활성화된 journal_mode 조회 (WAL 검증용)
+     */
+    getJournalMode(): string;
+    /**
+     * 마지막으로 디스크에 플러시된 LSN 번호
+     */
+    getLastFlushedLsn(): number;
+    /**
+     * 저장된 총 WAL 레코드 수
+     */
+    getPersistedCount(): number;
+    /**
+     * WAL 체크포인트 강제 실행 및 파일 핸들 안전 해제 (Windows EBUSY 잠금 방지)
+     */
+    close(): void;
+}

package/dist/wal/timeTravel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 무손실 시계열 시간 여행 및 역방향 델타 리플레이 엔진 (Causal Time-Travel Engine)
+ * - 구조적 공유(Structural Sharing): 변경되지 않은 문서 객체는 복제 없이 불변 참조 공유
+ * - 역방향 델타 리플레이(Reverse Delta Replay): 최신 상태에서 목표 시점(LSN/Timestamp)까지 역순 복원
+ * - 복원된 시점의 위키링크 커넥톰 그래프 및 BM25 전문 검색 색인을 완벽 재구성
+ */
+import { SynapseConnectome } from "../connectome";
+import { type CompilerTemporalMetric } from "./config";
+import type { TemporalRingBuffer } from "./ringBuffer";
+/** 두 시점(LSN) 간의 인과율 변경 차분 요약 */
+export interface CausalTimelineDiff {
+    readonly fromLsn: number;
+    readonly toLsn: number;
+    readonly addedDocuments: readonly string[];
+    readonly modifiedDocuments: readonly string[];
+    readonly deletedDocuments: readonly string[];
+    readonly edgesLinked: readonly string[];
+    readonly edgesUnlinked: readonly string[];
+    readonly compilerMetrics: readonly CompilerTemporalMetric[];
+}
+export declare class CausalTimeTravelEngine {
+    /**
+     * 특정 LSN(Log Sequence Number) 시점의 전체 시냅스 커넥톰을 즉시 복원
+     */
+    static asOfLsn(currentConnectome: SynapseConnectome, ringBuffer: TemporalRingBuffer, targetLsn: number): SynapseConnectome;
+    /**
+     * 특정 타임스탬프(밀리초 숫자 또는 ISO 문자열) 시점의 시냅스 커넥톰 복원
+     */
+    static asOf(currentConnectome: SynapseConnectome, ringBuffer: TemporalRingBuffer, timestampMsOrIso: number | string): SynapseConnectome;
+    /**
+     * 두 LSN 시점 사이의 문서 생성·수정·삭제 및 위키링크 시냅스 변화량 정밀 비교
+     */
+    static diffBetweenLsn(ringBuffer: TemporalRingBuffer, fromLsn: number, toLsn: number): CausalTimelineDiff;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "synapse-db",
-  "version": "0.3.0",
-  "description": "Universal Markdown-First & In-Memory Connectome Database with Wikilink Auto-Wiring, Korean N-gram BM25 & Obsidian Canvas Exporter",
+  "version": "0.3.1",
+  "description": "Universal Markdown-First & In-Memory Connectome Database with Causal-WAL Time-Travel, Zero-GC Ring Buffer, Bump Arena & Obsidian Canvas Exporter",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",