@obora/runtime 0.1.0

package/dist/_legacy/blackboard/snapshot/id-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module snapshot/id-utils
+ * @description ID 생성 유틸리티 (브라우저/Node.js 호환)
+ */
+/**
+ * 기본 ID 생성 함수
+ * @returns 고유 ID 문자열
+ * @description Node.js 환경에서는 crypto.randomUUID(), 브라우저 환경에서는 fallback 사용
+ */
+export declare function createDefaultId(): string;
+/**
+ * ID 생성자 타입
+ */
+export type IdGenerator = () => string;
+/**
+ * 기본 ID 생성자 생성
+ * @param customGenerator - 사용자 정의 ID 생성 함수 (선택)
+ * @returns ID 생성 함수
+ */
+export declare function createIdGenerator(customGenerator?: IdGenerator): IdGenerator;

package/dist/_legacy/blackboard/snapshot/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @packageDocumentation
+ * @module snapshot
+ * @description 스냅샷/복원 기능
+ */
+export * from './types';
+export { createDefaultId, createIdGenerator } from './id-utils';
+export { StateSerializer, calculateChecksum, calculateChecksumSync, verifyChecksum, verifyChecksumSync, } from './serializer';
+export type { SerializeOptions } from './serializer';
+export { compress, decompress, detectCompression } from './compression';
+export type { CompressionAlgorithm, CompressionOptions } from './compression';
+export { SnapshotManager, SnapshotRestoreError, } from './snapshot-manager';
+export type { SnapshotManagerOptions } from './snapshot-manager';
+export { SnapshotCreator } from './snapshot-creator';
+export type { SnapshotCreatorOptions } from './snapshot-creator';
+export { SnapshotValidator } from './snapshot-validator';
+export { SnapshotRestorer } from './snapshot-restorer';
+export type { SnapshotRestorerOptions } from './snapshot-restorer';
+export { SnapshotSerializer } from './snapshot-serializer';
+export { SnapshotComparer } from './snapshot-comparer';
+export type { SnapshotDiff, SectionDiff, SectionData } from './snapshot-comparer';

package/dist/_legacy/blackboard/snapshot/serializer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @module snapshot/serializer
+ * @description 직렬화/역직렬화 (브라우저/Node.js 호환)
+ */
+import type { BlackboardState } from "../types";
+import type { SerializedState } from "./types";
+/**
+ * 직렬화 옵션
+ */
+export interface SerializeOptions {
+    /** 날짜 형식 (기본: 'iso') */
+    dateFormat?: "iso" | "timestamp";
+    /** 정렬된 키 (재현 가능한 출력용) */
+    sortKeys?: boolean;
+    /** 들여쓰기 (기본: 0 = 압축) */
+    indent?: number;
+}
+/**
+ * 섹션 데이터 유효성 검증 결과
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * 상태 직렬화기
+ * @description Map, Date 등을 JSON 호환 형식으로 변환
+ */
+export declare class StateSerializer {
+    private options;
+    constructor(options?: SerializeOptions);
+    /**
+     * BlackboardState → SerializedState
+     * @param state - 원본 상태
+     * @returns 직렬화된 상태
+     */
+    serialize(state: BlackboardState): SerializedState;
+    /**
+     * 임의의 객체를 JSON 문자열로 직렬화
+     * @param obj - 직렬화할 객체
+     * @returns JSON 문자열
+     * @description Date, Map, Set 등을 포함한 일반 객체 직렬화
+     */
+    serializeJSON(obj: unknown): string;
+    /**
+     * JSON 문자열을 객체로 역직렬화
+     * @param json - JSON 문자열
+     * @returns 역직렬화된 객체
+     * @throws {Error} JSON 파싱 실패 시
+     * @description JSON.parse를 사용한 기본 역직렬화
+     */
+    deserializeJSON<T = unknown>(json: string): T;
+    /**
+     * SerializedState → BlackboardState
+     * @param serialized - 직렬화된 상태
+     * @returns 복원된 상태
+     */
+    deserialize(serialized: SerializedState): BlackboardState;
+    /**
+     * JSON 문자열로 변환
+     * @param state - 원본 상태
+     * @returns JSON 문자열
+     */
+    toJSON(state: BlackboardState): string;
+    /**
+     * JSON 문자열에서 복원
+     * @param json - JSON 문자열
+     * @returns 복원된 상태
+     * @throws {Error} JSON 파싱 실패 시 명확한 에러 메시지 (P1: JSON.parse 에러 처리)
+     */
+    fromJSON(json: string): BlackboardState;
+    /**
+     * Map → Array 변환
+     */
+    private serializeMap;
+    /**
+     * Array → Map 변환
+     */
+    private deserializeMap;
+    /**
+     * Date → string 변환
+     */
+    private serializeDate;
+    /**
+     * string → Date 변환
+     */
+    private deserializeDate;
+    /**
+     * Branded ID 복원
+     * @param obj - 원본 ID 값 (일반적으로 문자열)
+     * @returns 브랜드 타입으로 캐스팅된 ID
+     * @description 문자열 타입 안전성 검증 후 반환
+     */
+    private restoreIds;
+}
+/**
+ * Web Crypto API를 사용한 체크섬 계산 (비동기)
+ * @param data - 대상 데이터
+ * @returns SHA-256 해시
+ */
+export declare function calculateChecksum(data: unknown): Promise<string>;
+/**
+ * Web Crypto API를 사용한 체크섬 검증 (비동기)
+ * @param data - 대상 데이터
+ * @param expectedChecksum - 예상 체크섬
+ * @returns 일치 여부
+ */
+export declare function verifyChecksum(data: unknown, expectedChecksum: string): Promise<boolean>;
+/**
+ * 동기 체크섬 계산 (Node.js 전용)
+ * @param data - 대상 데이터
+ * @returns SHA-256 해시
+ * @description 테스트 환경 등에서 동기 체크섬이 필요한 경우 사용
+ */
+export declare function calculateChecksumSync(data: unknown): string;
+/**
+ * 동기 체크섬 검증 (Node.js 전용)
+ * @param data - 대상 데이터
+ * @param expectedChecksum - 예상 체크섬
+ * @returns 일치 여부
+ * @description 테스트 환경 등에서 동기 체크섬이 필요한 경우 사용
+ */
+export declare function verifyChecksumSync(data: unknown, expectedChecksum: string): boolean;

package/dist/_legacy/blackboard/snapshot/snapshot-comparer.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @module snapshot/snapshot-comparer
+ * @description 스냅샷 비교 담당
+ */
+import type { Snapshot } from './types';
+/**
+ * 스냅샷 차이점
+ */
+export interface SnapshotDiff {
+    /** 메타데이터 차이 */
+    meta: {
+        versionDiff: number;
+        timeDiff: number;
+    };
+    /** 섹션별 차이 */
+    sections: {
+        state: SectionDiff;
+        knowledge: SectionDiff;
+        decisions: SectionDiff;
+    };
+    /** 차이점 존재 여부 */
+    hasDifferences: boolean;
+    /** 상세 변경 정보 */
+    details?: {
+        phase?: {
+            before: unknown;
+            after: unknown;
+        };
+        [key: string]: unknown;
+    };
+}
+/**
+ * 섹션 데이터 타입
+ */
+export type SectionData = Record<string, unknown>;
+/**
+ * 섹션 차이점
+ */
+export interface SectionDiff {
+    /** 추가된 항목 수 */
+    added: number;
+    /** 제거된 항목 수 */
+    removed: number;
+    /** 변경된 항목 수 */
+    modified: number;
+    /** 상세 변경 목록 (경로 → [이전, 이후]) */
+    changes: Map<string, [unknown, unknown]>;
+}
+/**
+ * 스냅샷 비교자
+ * @description 스냅샷 비교 전담 클래스
+ */
+export declare class SnapshotComparer {
+    /**
+     * Optional logger for error reporting
+     * If not provided, errors are silently ignored (fail-safe)
+     */
+    private logger?;
+    /**
+     * Set the logger for error reporting
+     */
+    setLogger(logger: (msg: string, error?: string) => void): void;
+    /**
+     * 스냅샷 비교
+     * @param a - 첫 번째 스냅샷
+     * @param b - 두 번째 스냅샷
+     * @returns 차이점 목록
+     */
+    compare(a: Snapshot, b: Snapshot): SnapshotDiff;
+    /**
+     * 섹션 차이점 생성
+     * @param data1 - 첫 번째 데이터
+     * @param data2 - 두 번째 데이터
+     * @returns 섹션 차이점
+     */
+    createSectionDiff(data1: SectionData, data2: SectionData): SectionDiff;
+    /**
+     * Generic section data extraction
+     * @param snapshot - 스냅샷
+     * @param section - 섹션 이름
+     * @returns 섹션 데이터
+     */
+    private extractSection;
+    /**
+     * 상태 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 상태 데이터
+     */
+    extractStateData(snapshot: Snapshot): SectionData;
+    /**
+     * 지식 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 지식 데이터
+     */
+    extractKnowledgeData(snapshot: Snapshot): SectionData;
+    /**
+     * 의사결정 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 의사결정 데이터
+     */
+    extractDecisionsData(snapshot: Snapshot): SectionData;
+}

package/dist/_legacy/blackboard/snapshot/snapshot-creator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module snapshot/snapshot-creator
+ * @description 스냅샷 생성 담당
+ */
+import type { BlackboardState } from "../types";
+import type { Snapshot, SnapshotMeta, CreateSnapshotOptions } from "./types";
+import { type IdGenerator } from "./id-utils";
+/**
+ * 스냅샷 생성자 설정
+ */
+export interface SnapshotCreatorOptions {
+    /** 자동 압축 임계값 (바이트, 기본: 10KB) */
+    autoCompressThreshold?: number;
+    /** 기본 압축 사용 */
+    defaultCompress?: boolean;
+    /** ID 생성 함수 */
+    idGenerator?: IdGenerator;
+}
+/**
+ * 스냅샷 생성자
+ * @description 스냅샷 생성 전담 클래스
+ */
+export declare class SnapshotCreator {
+    private serializer;
+    private options;
+    constructor(options?: SnapshotCreatorOptions);
+    /**
+     * 옵션 정규화
+     */
+    private normalizeOptions;
+    /**
+     * ID 생성자 가져오기
+     */
+    getIdGenerator(): IdGenerator;
+    /**
+     * 스냅샷 생성 (동기)
+     * @param state - 현재 Blackboard 상태
+     * @param options - 생성 옵션
+     * @returns 스냅샷
+     */
+    createSnapshot(state: BlackboardState, options?: CreateSnapshotOptions): Snapshot;
+    /**
+     * 메타데이터만 포함된 스냅샷 생성 (동기)
+     * @param state - 현재 상태
+     * @param description - 설명
+     * @returns 메타 전용 스냅샷
+     */
+    createMetaSnapshot(state: BlackboardState, description?: string): SnapshotMeta;
+}

package/dist/_legacy/blackboard/snapshot/snapshot-manager.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @module snapshot/snapshot-manager
+ * @description 스냅샷 관리자 (파사드 패턴)
+ */
+import type { BlackboardState } from '../types';
+import type { Snapshot, SnapshotMeta, CreateSnapshotOptions, RestoreSnapshotOptions, SnapshotValidationResult } from './types';
+import type { SnapshotCreatorOptions } from './snapshot-creator';
+import type { SnapshotRestorerOptions } from './snapshot-restorer';
+import type { SnapshotDiff, SectionDiff, SectionData } from './snapshot-comparer';
+import { SnapshotRestoreError } from './snapshot-restorer';
+/**
+ * 스냅샷 목록 필터 옵션
+ */
+export interface ListSnapshotOptions {
+    /** 태그로 필터링 */
+    tags?: string[];
+    /** 세션 ID로 필터링 */
+    sessionId?: string;
+    /** 정렬 기준 */
+    sortBy?: 'date' | 'id';
+    /** 정렬 순서 */
+    order?: 'asc' | 'desc';
+}
+/**
+ * 스냅샷 관리자 설정
+ */
+export interface SnapshotManagerOptions extends SnapshotCreatorOptions, SnapshotRestorerOptions {
+    /** 자동 압축 임계값 (바이트, 기본: 10KB) */
+    autoCompressThreshold?: number;
+    /** 기본 압축 사용 */
+    defaultCompress?: boolean;
+    /** ID 생성 함수 */
+    idGenerator?: () => string;
+}
+/**
+ * 스냅샷 복원 에러
+ */
+export { SnapshotRestoreError };
+/**
+ * 스냅샷 관리자
+ * @description Blackboard 상태의 스냅샷 생성, 검증, 복원 담당
+ *
+ * 파사드 패턴으로 각 전문 클래스를 조합하여 기존 API 유지
+ *
+ * @example
+ * ```typescript
+ * const manager = new SnapshotManager();
+ *
+ * // 스냅샷 생성
+ * const snapshot = await manager.createSnapshot(board.getState(), {
+ *   description: 'Before major decision',
+ *   tags: ['checkpoint', 'decision-001'],
+ *   compress: true,
+ * });
+ *
+ * // JSON으로 저장
+ * const json = manager.toJSON(snapshot);
+ * fs.writeFileSync('snapshot.json', json);
+ *
+ * // JSON에서 로드
+ * const loaded = manager.fromJSON(fs.readFileSync('snapshot.json', 'utf-8'));
+ *
+ * // 검증
+ * const validation = await manager.validate(loaded);
+ * if (!validation.valid) {
+ *   console.error('Invalid snapshot:', validation.errors);
+ * }
+ *
+ * // 복원
+ * const restoredState = manager.restore(loaded, {
+ *   newSessionId: true,
+ * });
+ * board.replaceState(restoredState);
+ * ```
+ */
+export declare class SnapshotManager {
+    private creator;
+    private validator;
+    private restorer;
+    private serializer;
+    private comparer;
+    private storage;
+    constructor(options?: SnapshotManagerOptions);
+    /**
+     * 스냅샷 저장 (내부)
+     */
+    private storeSnapshot;
+    /**
+     * 저장된 스냅샷 목록 조회
+     * @param options - 필터 및 정렬 옵션
+     * @returns 스냅샷 목록
+     */
+    list(options?: ListSnapshotOptions): Snapshot[];
+    /**
+     * ID로 스냅샷 조회
+     * @param id - 스냅샷 ID
+     * @returns 스냅샷 또는 undefined
+     */
+    get(id: string): Snapshot | undefined;
+    /**
+     * ID로 스냅샷 삭제
+     * @param id - 스냅샷 ID
+     * @returns 삭제 성공 여부
+     */
+    delete(id: string): boolean;
+    /**
+     * 스냅샷 생성 (동기)
+     * @param state - 현재 Blackboard 상태
+     * @param options - 생성 옵션
+     * @returns 스냅샷
+     */
+    createSnapshot(state: BlackboardState, options?: CreateSnapshotOptions): Snapshot;
+    /**
+     * 메타데이터만 포함된 스냅샷 생성 (동기)
+     * @param state - 현재 상태
+     * @param description - 설명
+     * @returns 메타 전용 스냅샷
+     */
+    createMetaSnapshot(state: BlackboardState, description?: string): SnapshotMeta;
+    /**
+     * 스냅샷 검증 (동기)
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     */
+    validate(snapshot: Snapshot): SnapshotValidationResult;
+    /**
+     * 스냅샷 검증 (비동기)
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     */
+    validateAsync(snapshot: Snapshot): Promise<SnapshotValidationResult>;
+    /**
+     * 버전 호환성 체크
+     * @param formatVersion - 스냅샷 형식 버전
+     * @returns 호환 여부 및 상세 정보
+     */
+    checkVersionCompatibility(formatVersion: string): {
+        compatible: boolean;
+        current: string;
+        snapshot: string;
+        migrationRequired: boolean;
+    };
+    /**
+     * 동기 체크섬 검증 (구조적 검증만, 체크섬 제외)
+     * @description restore()에서 사용하는 동기 검증 메서드
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     */
+    validateSyncStructure(snapshot: Snapshot): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * 스냅샷에서 상태 복원
+     * @param snapshot - 스냅샷
+     * @param options - 복원 옵션
+     * @returns 복원된 상태
+     * @throws {SnapshotRestoreError} 복원 실패 시
+     * @description
+     * **옵션 동작:**
+     * - `skipVersionCheck`: 포맷 버전 호환성 검사 건너뜀
+     * - `skipStructuralValidation`: 구조적 검증 건너뜀 (validateSync)
+     * - `resetVersion`: 상태 버전 0으로 초기화 (기본: true)
+     * - `newSessionId`: 새 세션 ID 생성 (기본: true)
+     */
+    restore(snapshot: Snapshot, options?: RestoreSnapshotOptions): BlackboardState;
+    /**
+     * 부분 복원 (특정 섹션만)
+     * @param snapshot - 스냅샷
+     * @param currentState - 현재 상태
+     * @param sections - 복원할 섹션
+     * @returns 병합된 상태
+     */
+    partialRestore(snapshot: Snapshot, currentState: BlackboardState, sections: ('state' | 'knowledge' | 'decisions')[]): BlackboardState;
+    /**
+     * 스냅샷 → JSON 문자열
+     * @param snapshot - 스냅샷
+     * @param pretty - 예쁜 출력 여부
+     * @returns JSON 문자열
+     */
+    toJSON(snapshot: Snapshot, pretty?: boolean): string;
+    /**
+     * JSON 문자열 → 스냅샷
+     * @param json - JSON 문자열
+     * @returns 스냅샷
+     * @throws {Error} JSON 파싱 실패 시 명확한 에러 메시지
+     */
+    fromJSON(json: string): Snapshot;
+    /**
+     * 스냅샷 → Uint8Array (바이너리)
+     * @param snapshot - 스냅샷
+     * @returns Uint8Array
+     */
+    toUint8Array(snapshot: Snapshot): Uint8Array;
+    /**
+     * Uint8Array → 스냅샷
+     * @param bytes - 바이트 배열
+     * @returns 스냅샷
+     * @throws {Error} 디코딩 실패 시 명확한 에러 메시지
+     */
+    fromUint8Array(bytes: Uint8Array): Snapshot;
+    /**
+     * 스냅샷 비교
+     * @param a - 첫 번째 스냅샷
+     * @param b - 두 번째 스냅샷
+     * @returns 차이점 목록
+     */
+    compare(a: Snapshot, b: Snapshot): SnapshotDiff;
+    /**
+     * 섹션 차이점 생성
+     * @param data1 - 첫 번째 데이터
+     * @param data2 - 두 번째 데이터
+     * @returns 섹션 차이점
+     */
+    createSectionDiff(data1: SectionData, data2: SectionData): SectionDiff;
+    /**
+     * 상태 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 상태 데이터
+     */
+    extractStateData(snapshot: Snapshot): SectionData;
+    /**
+     * 지식 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 지식 데이터
+     */
+    extractKnowledgeData(snapshot: Snapshot): SectionData;
+    /**
+     * 의사결정 데이터 추출
+     * @param snapshot - 스냅샷
+     * @returns 의사결정 데이터
+     */
+    extractDecisionsData(snapshot: Snapshot): SectionData;
+    /**
+     * 스냅샷 메타데이터만 추출
+     */
+    extractMeta(snapshot: Snapshot): SnapshotMeta;
+    /**
+     * 스냅샷 크기 계산 (숫자)
+     * @param snapshot - 스냅샷
+     * @returns 바이트 크기
+     */
+    size(snapshot: Snapshot): number;
+    /**
+     * 스냅샷 크기 계산 (상세)
+     */
+    calculateSize(snapshot: Snapshot): {
+        total: number;
+        data: number;
+        meta: number;
+        compressed: boolean;
+    };
+}

package/dist/_legacy/blackboard/snapshot/snapshot-restorer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @module snapshot/snapshot-restorer
+ * @description 스냅샷 복원 담당
+ */
+import type { BlackboardState } from '../types';
+import type { Snapshot, RestoreSnapshotOptions } from './types';
+/**
+ * 스냅샷 복원 에러
+ */
+export declare class SnapshotRestoreError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * 스냅샷 복원자 설정
+ */
+export interface SnapshotRestorerOptions {
+    /** ID 생성 함수 */
+    idGenerator?: () => string;
+}
+/**
+ * 스냅샷 복원자
+ * @description 스냅샷 복원 전담 클래스
+ */
+export declare class SnapshotRestorer {
+    private serializer;
+    private validator;
+    private idGenerator;
+    constructor(options?: SnapshotRestorerOptions);
+    /**
+     * 스냅샷에서 상태 복원
+     * @param snapshot - 스냅샷
+     * @param options - 복원 옵션
+     * @returns 복원된 상태
+     * @throws {SnapshotRestoreError} 복원 실패 시
+     * @description
+     * **옵션 동작:**
+     * - `skipVersionCheck`: 포맷 버전 호환성 검사 건너뜀
+     * - `skipStructuralValidation`: 구조적 검증 건너뜀 (validateSync)
+     *   - 참고: 체크섬 검증은 validate()에서 수행됨
+     * - `resetVersion`: 상태 버전 0으로 초기화 (기본: true)
+     * - `newSessionId`: 새 세션 ID 생성 (기본: true)
+     */
+    restore(snapshot: Snapshot, options?: RestoreSnapshotOptions): BlackboardState;
+    /**
+     * 부분 복원 (특정 섹션만)
+     * @param snapshot - 스냅샷
+     * @param currentState - 현재 상태
+     * @param sections - 복원할 섹션
+     * @returns 병합된 상태
+     */
+    partialRestore(snapshot: Snapshot, currentState: BlackboardState, sections: ('state' | 'knowledge' | 'decisions')[]): BlackboardState;
+}

package/dist/_legacy/blackboard/snapshot/snapshot-serializer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module snapshot/snapshot-serializer
+ * @description 스냅샷 직렬화 담당
+ */
+import type { Snapshot } from './types';
+/**
+ * 스냅샷 직렬화 옵션
+ */
+export interface SnapshotSerializeOptions {
+    /** 예쁜 출력 여부 */
+    pretty?: boolean;
+}
+/**
+ * 스냅샷 직렬화자
+ * @description 스냅샷 직렬화/역직렬화 전담 클래스
+ */
+export declare class SnapshotSerializer {
+    /**
+     * 스냅샷 → JSON 문자열
+     * @param snapshot - 스냅샷
+     * @param pretty - 예쁜 출력 여부
+     * @returns JSON 문자열
+     */
+    toJSON(snapshot: Snapshot, pretty?: boolean): string;
+    /**
+     * JSON 문자열 → 스냅샷
+     * @param json - JSON 문자열
+     * @returns 스냅샷
+     * @throws {Error} JSON 파싱 실패 시 명확한 에러 메시지
+     */
+    fromJSON(json: string): Snapshot;
+    /**
+     * 스냅샷 → Uint8Array (바이너리)
+     * @param snapshot - 스냅샷
+     * @returns Uint8Array
+     */
+    toUint8Array(snapshot: Snapshot): Uint8Array;
+    /**
+     * Uint8Array → 스냅샷
+     * @param bytes - 바이트 배열
+     * @returns 스냅샷
+     * @throws {Error} 디코딩 실패 시 명확한 에러 메시지
+     */
+    fromUint8Array(bytes: Uint8Array): Snapshot;
+}