@obora/runtime 0.1.0

package/dist/blackboard/snapshot/compression.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @module snapshot/compression
+ * @description 압축 유틸리티 (브라우저/Node.js 호환)
+ */
+/**
+ * 압축 알고리즘
+ * @note brotli는 pako에서 지원하지 않음
+ */
+export type CompressionAlgorithm = 'gzip' | 'none';
+/**
+ * 압축 레벨 (테스트 호환 타입)
+ */
+export type CompressionLevel = 'none' | 'fast' | 'balanced' | 'max';
+/**
+ * 내부 pako 압축 레벨 숫자 타입
+ */
+type PakoCompressionLevel = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * 압축 옵션
+ */
+export interface CompressionOptions {
+    /** 알고리즘 (기본: 'gzip') */
+    algorithm?: CompressionAlgorithm;
+    /** 압축 레벨 (기본: 'balanced') */
+    level?: CompressionLevel | PakoCompressionLevel;
+    /** 출력 형식 (기본: 'base64') */
+    outputFormat?: 'base64' | 'buffer' | 'uint8array';
+    /** 메타데이터 포함 여부 */
+    includeMetadata?: boolean;
+}
+/**
+ * 압축 해제 옵션
+ */
+export interface DecompressionOptions {
+    /** 압축 알고리즘 */
+    algorithm?: CompressionAlgorithm;
+    /** 입력 형식 (기본: 'base64') */
+    inputFormat?: 'base64' | 'buffer' | 'uint8array';
+    /** 유효성 검사 건너뛰기 (algorithm='none'인 경우 자동 true) */
+    skipValidation?: boolean;
+}
+/**
+ * 압축 메타데이터
+ */
+export interface CompressionMetadata {
+    /** 원본 크기 */
+    originalSize: number;
+    /** 압축된 크기 */
+    compressedSize: number;
+    /** 사용된 알고리즘 */
+    algorithm: CompressionAlgorithm;
+    /** 사용된 압축 레벨 */
+    level: CompressionLevel | PakoCompressionLevel;
+    /** 타임스탬프 */
+    timestamp: string;
+}
+/**
+ * 메타데이터가 포함된 압축 결과
+ */
+export interface CompressedWithMeta {
+    /** 압축된 데이터 */
+    data: string;
+    /** 메타데이터 */
+    metadata: CompressionMetadata;
+}
+/**
+ * 압축 통계
+ */
+export interface CompressionStats {
+    /** 원본 크기 */
+    originalSize: number;
+    /** 압축된 크기 */
+    compressedSize: number;
+    /** 압축 비율 (originalSize / compressedSize) */
+    ratio: number;
+    /** 절감된 크기 (bytes) */
+    savings: number;
+    /** 절감 비율 (%) */
+    savingsPercent: number;
+}
+/**
+ * 데이터 압축
+ * @param data - 압축할 데이터 (string | Uint8Array | Buffer)
+ * @param options - 압축 옵션
+ * @returns 압축된 데이터 (string | Uint8Array | Buffer)
+ */
+export declare function compress(data: string | Uint8Array | Buffer, options?: CompressionOptions): string | Uint8Array | Buffer;
+/**
+ * 데이터 압축 해제
+ * @param compressed - 압축된 데이터
+ * @param options - 압축 해제 옵션
+ * @returns 원본 데이터
+ * @throws {Error} 데이터 크기 제한 초과 시
+ */
+export declare function decompress(compressed: string | Uint8Array | Buffer, options?: DecompressionOptions): string | Uint8Array | Buffer;
+/**
+ * 압축 여부 감지
+ * @param data - 검사할 데이터
+ * @returns 압축 알고리즘 또는 null
+ */
+export declare function detectCompression(data: string): CompressionAlgorithm | null;
+/**
+ * 체크섬 계산 (비동기)
+ */
+export declare function calculateChecksumAsync(data: string): Promise<string>;
+/**
+ * 체크섬 검증
+ */
+export declare function verifyChecksum(data: string, expectedChecksum: string): Promise<boolean>;
+/**
+ * Compressor 클래스 - 상태 저장형 압축
+ */
+export declare class Compressor {
+    private options;
+    private history;
+    constructor(options?: CompressionOptions);
+    /**
+     * 데이터 압축
+     */
+    compress(data: string | Uint8Array | Buffer): Uint8Array;
+    /**
+     * 데이터 압축 해제
+     */
+    decompress(data: Uint8Array): string;
+    /**
+     * 비동기 압축
+     */
+    compressAsync(data: string | Uint8Array | Buffer): Promise<Uint8Array>;
+    /**
+     * 비동기 압축 해제
+     */
+    decompressAsync(data: Uint8Array): Promise<string>;
+    /**
+     * 압축 비율 계산
+     */
+    ratio(originalSize: number, compressedSize: number): number;
+    /**
+     * 압축 통계 계산
+     */
+    stats(originalSize: number, compressedSize: number): CompressionStats;
+    /**
+     * 내부 통계 계산
+     */
+    private calculateStatsInternal;
+    /**
+     * 메타데이터 포함 압축
+     */
+    compressWithMeta(data: string | Uint8Array | Buffer): CompressedWithMeta;
+    /**
+     * 메타데이터 포함 압축 해제
+     */
+    decompressWithMeta(compressed: CompressedWithMeta | string): string;
+    /**
+     * 기록된 압축 통계 가져오기
+     */
+    getHistory(): CompressionStats[];
+    /**
+     * 기록된 통계 지우기
+     */
+    clearHistory(): void;
+    /**
+     * 옵션 업데이트
+     */
+    setOptions(options: Partial<CompressionOptions>): void;
+    /**
+     * 현재 옵션 가져오기
+     */
+    getOptions(): CompressionOptions;
+}
+export {};

package/dist/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/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/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/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/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;
+}