@obora/runtime 0.1.0

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

@@ -0,0 +1,55 @@
+/**
+ * @module snapshot/snapshot-validator
+ * @description 스냅샷 검증 담당
+ */
+import type { Snapshot, SnapshotValidationResult } from "./types";
+import { StateSerializer } from "./serializer";
+/**
+ * 스냅샷 검증자
+ * @description 스냅샷 검증 전담 클래스
+ */
+export declare class SnapshotValidator {
+    private serializer;
+    constructor(serializer?: StateSerializer);
+    /**
+     * 스냅샷 검증 (비동기)
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     */
+    validate(snapshot: Snapshot): Promise<SnapshotValidationResult>;
+    /**
+     * 스냅샷 검증 (동기)
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     * @description 테스트 환경 등에서 동기 검증이 필요한 경우 사용
+     */
+    validateSync(snapshot: Snapshot): SnapshotValidationResult;
+    /**
+     * 버전 호환성 체크
+     * @param formatVersion - 스냅샷 형식 버전
+     * @returns 호환 여부 및 상세 정보
+     */
+    checkVersionCompatibility(formatVersion: string): {
+        compatible: boolean;
+        current: string;
+        snapshot: string;
+        migrationRequired: boolean;
+    };
+    /**
+     * 동기 체크섬 검증 (구조적 검증만, 체크섬 제외)
+     * @description restore()에서 사용하는 동기 검증 메서드
+     * 체크섬 검증은 비동기이므로 validate()에서 수행해야 함
+     * @param snapshot - 검증할 스냅샷
+     * @returns 검증 결과
+     */
+    validateSyncStructure(snapshot: Snapshot): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * 런타임 구조 검증 (P0: agents/tasks/opinions)
+     * @description 역직렬화 후 실제 데이터 구조 검증
+     * P1: 에러 수집 모드 (break 제거)
+     */
+    private validateRuntimeStructure;
+}

package/dist/_legacy/blackboard/snapshot/type-guards.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module snapshot/type-guards
+ * @description 타입 가드 함수들 (중복 제거)
+ */
+import type { SerializedState } from './types';
+/**
+ * 타입 가드: SerializedState 여부 확인
+ * @description P1: 검증 범위 확대 - state/knowledge/decisions 필드 검증 추가
+ * @param value - 확인할 값
+ * @returns SerializedState 타입 여부
+ */
+export declare function isSerializedState(value: unknown): value is SerializedState;

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

@@ -0,0 +1,151 @@
+/**
+ * @module snapshot/types
+ * @description 스냅샷 타입 정의
+ */
+import type { SessionId } from "../types";
+/**
+ * 스냅샷 형식 버전
+ * @description 역직렬화 시 호환성 체크에 사용
+ */
+export declare const SNAPSHOT_FORMAT_VERSION = "1.0.0";
+/**
+ * 스냅샷 메타데이터
+ */
+export interface SnapshotMeta {
+    /** 스냅샷 ID */
+    readonly id: string;
+    /** 스냅샷 형식 버전 */
+    readonly formatVersion: string;
+    /** 생성 시간 */
+    readonly createdAt: Date;
+    /** 원본 세션 ID */
+    readonly sessionId: SessionId;
+    /** 원본 상태 버전 */
+    readonly stateVersion: number;
+    /** 스냅샷 설명 (선택) */
+    readonly description?: string;
+    /** 스냅샷 태그 (선택) */
+    readonly tags?: string[];
+    /** 체크섬 (무결성 검증용) */
+    readonly checksum: string;
+    /** 압축 데이터 체크섬 */
+    readonly compressedChecksum?: string;
+    /** 압축 여부 */
+    readonly compressed: boolean;
+    /** 원본 크기 (바이트) */
+    readonly originalSize: number;
+    /** 압축 크기 (바이트, 압축 시) */
+    readonly compressedSize?: number;
+}
+/**
+ * 직렬화된 상태
+ * @description Map, Date 등이 JSON 호환 형식으로 변환됨
+ */
+export interface SerializedState {
+    meta: {
+        version: number;
+        lastUpdated: string;
+        sessionId: string;
+        createdAt: string;
+    };
+    state: {
+        phase: string;
+        context: Record<string, unknown>;
+        agents: Array<[string, unknown]>;
+        tasks: Array<[string, unknown]>;
+    };
+    knowledge: {
+        facts: unknown[];
+        inferences: unknown[];
+        patterns: unknown[];
+    };
+    decisions: {
+        current: unknown | null;
+        pending: unknown[];
+        opinions: Array<[string, unknown]>;
+        history: unknown[];
+        voting?: Record<string, unknown>;
+    };
+}
+/**
+ * 전체 스냅샷 구조
+ */
+export interface Snapshot {
+    /** 메타데이터 */
+    meta: SnapshotMeta;
+    /** 직렬화된 상태 데이터 */
+    data: SerializedState | string;
+}
+/**
+ * 스냅샷 생성 옵션
+ */
+export interface CreateSnapshotOptions {
+    /** 스냅샷 설명 */
+    description?: string;
+    /** 태그 */
+    tags?: string[];
+    /** 압축 사용 여부 (기본: false) */
+    compress?: boolean;
+    /** 특정 섹션만 포함 */
+    includeSections?: ("state" | "knowledge" | "decisions")[];
+    /** 메타만 포함 (상태 제외) */
+    metaOnly?: boolean;
+    /** 내부 저장소에 저장 여부 */
+    store?: boolean;
+}
+/**
+ * 스냅샷 복원 옵션
+ */
+export interface RestoreSnapshotOptions {
+    /** 버전 체크 건너뛰기 */
+    skipVersionCheck?: boolean;
+    /** 구조적 검증 건너뛰기 (validateSync) */
+    skipStructuralValidation?: boolean;
+    /** 검증 건너뛰기 (별칭: skipStructuralValidation) */
+    skipValidation?: boolean;
+    /** 특정 섹션만 복원 */
+    restoreSections?: ("state" | "knowledge" | "decisions")[];
+    /** 복원 후 버전 리셋 여부 (기본: true) */
+    resetVersion?: boolean;
+    /** 새 세션 ID 발급 (기본: true) */
+    newSessionId?: boolean;
+}
+/**
+ * 스냅샷 검증 결과
+ */
+export interface SnapshotValidationResult {
+    /** 유효 여부 */
+    valid: boolean;
+    /** 에러 목록 */
+    errors: SnapshotValidationError[];
+    /** 경고 목록 */
+    warnings: SnapshotValidationWarning[];
+}
+/**
+ * 검증 에러
+ */
+export interface SnapshotValidationError {
+    code: "VERSION_MISMATCH" | "CHECKSUM_INVALID" | "DATA_CORRUPTED" | "FORMAT_INVALID" | "MISSING_FIELD";
+    message: string;
+    details?: unknown;
+}
+/**
+ * 검증 경고
+ */
+export interface SnapshotValidationWarning {
+    code: "DEPRECATED_FORMAT" | "UNKNOWN_FIELDS" | "PARTIAL_DATA";
+    message: string;
+    details?: unknown;
+}
+/**
+ * 스냅샷 마이그레이션 인터페이스
+ * @description 스냅샷 데이터 버전 간 마이그레이션을 위한 인터페이스
+ */
+export interface SnapshotMigration {
+    /** 원본 버전 */
+    fromVersion: number;
+    /** 대상 버전 */
+    toVersion: number;
+    /** 마이그레이션 함수 */
+    migrate(data: unknown): unknown;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @module snapshot/utils
+ * @description 유틸리티 함수들 (중복 제거)
+ */
+import type { Snapshot, SerializedState } from "./types";
+/**
+ * JSON.stringify replacer for key sorting
+ * @param key - Property key
+ * @param value - Property value
+ * @returns Value with sorted keys for objects
+ */
+export declare function sortedKeyReplacer(key: string, value: unknown): unknown;
+/**
+ * 스냅샷 데이터 압축 해제 (공통 헬퍼)
+ * @description P0: decompressData 로직 중복 제거를 위한 공통 함수
+ * @param snapshot - 스냅샷
+ * @returns 역직렬화된 상태 데이터
+ * @throws {Error} 압축 해제 실패 또는 타입 불일치 시
+ */
+export declare function decompressSnapshotData(snapshot: Snapshot): SerializedState;

package/dist/_legacy/blackboard/types/agent.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @module agent
+ * @description 에이전트 관련 타입 정의
+ */
+import type { Timestamped } from "./base";
+import type { AgentId, TaskId } from "./base";
+/**
+ * 에이전트 상태 enum
+ * @description 에이전트의 현재 활동 상태를 나타냄
+ */
+export declare enum AgentStatusEnum {
+    /** 유휴 상태 - 작업 대기 중 */
+    IDLE = "idle",
+    /** 작업 중 - 활성 상태 */
+    BUSY = "busy",
+    /** 오류 상태 - 복구 필요 */
+    ERROR = "error",
+    /** 중지됨 */
+    STOPPED = "stopped"
+}
+/**
+ * 에이전트 역할 타입
+ * @description 에이전트가 수행할 수 있는 역할
+ */
+export type AgentRole = "analyst" | "executor" | "verifier" | "director";
+/**
+ * 에이전트 상태 정보
+ * @description 에이전트의 현재 상태와 작업 정보를 담는 인터페이스
+ *
+ * @example
+ * ```typescript
+ * const agentStatus: AgentStatus = {
+ *   id: createAgentId('agent-001'),
+ *   role: 'analyst',
+ *   status: AgentStatusEnum.BUSY,
+ *   currentTask: createTaskId('task-001'),
+ *   lastHeartbeat: new Date(),
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   metadata: { model: 'gpt-4' }
+ * };
+ * ```
+ */
+export interface AgentStatus extends Timestamped {
+    /** 에이전트 고유 ID */
+    readonly id: AgentId;
+    /** 에이전트 역할 */
+    readonly role: AgentRole;
+    /** 현재 상태 */
+    status: AgentStatusEnum;
+    /** 현재 수행 중인 작업 (없으면 null) */
+    currentTask: TaskId | null;
+    /** 마지막 하트비트 시간 */
+    lastHeartbeat: Date;
+    /** 추가 메타데이터 */
+    metadata: Record<string, unknown>;
+}
+/**
+ * 에이전트 상태 업데이트 옵션
+ * @description 부분 업데이트를 위한 선택적 필드 인터페이스
+ */
+export interface AgentStatusUpdate {
+    /** 새로운 상태 */
+    status?: AgentStatusEnum;
+    /** 새로운 현재 작업 */
+    currentTask?: TaskId | null;
+    /** 마지막 하트비트 시간 */
+    lastHeartbeat?: Date;
+    /** 업데이트할 메타데이터 */
+    metadata?: Partial<Record<string, unknown>>;
+}
+/**
+ * 에이전트 통계
+ * @description 에이전트의 성능 및 활동 통계
+ */
+export interface AgentStats {
+    /** 에이전트 ID */
+    agentId: AgentId;
+    /** 완료한 작업 수 */
+    tasksCompleted: number;
+    /** 실패한 작업 수 */
+    tasksFailed: number;
+    /** 총 작업 시간 (밀리초) */
+    totalTaskTime: number;
+    /** 평균 작업 시간 (밀리초) */
+    averageTaskTime: number;
+    /** 마지막 활동 시간 */
+    lastActiveTime: Date;
+}

package/dist/_legacy/blackboard/types/base.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @module base
+ * @description 기본 타입 정의 - ID 타입, 공통 인터페이스
+ */
+/**
+ * 고유 식별자 타입들
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+/** 에이전트 고유 ID 타입 */
+export type AgentId = string & {
+    readonly __brand: 'AgentId';
+};
+/** 작업 고유 ID 타입 */
+export type TaskId = string & {
+    readonly __brand: 'TaskId';
+};
+/** 안건 고유 ID 타입 */
+export type AgendaId = string & {
+    readonly __brand: 'AgendaId';
+};
+/** 세션 고유 ID 타입 */
+export type SessionId = string & {
+    readonly __brand: 'SessionId';
+};
+/** 사실 고유 ID 타입 */
+export type FactId = string & {
+    readonly __brand: 'FactId';
+};
+/** 추론 고유 ID 타입 */
+export type InferenceId = string & {
+    readonly __brand: 'InferenceId';
+};
+/** 패턴 고유 ID 타입 */
+export type PatternId = string & {
+    readonly __brand: 'PatternId';
+};
+/** 의견 고유 ID 타입 */
+export type OpinionId = string & {
+    readonly __brand: 'OpinionId';
+};
+/**
+ * 타입 가드 및 생성 함수
+ */
+/**
+ * 에이전트 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 AgentId
+ * @example
+ * ```typescript
+ * const agentId = createAgentId('agent-001');
+ * // 타입: AgentId
+ * ```
+ */
+export declare function createAgentId(id: string): AgentId;
+/**
+ * 작업 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 TaskId
+ * @example
+ * ```typescript
+ * const taskId = createTaskId('task-001');
+ * // 타입: TaskId
+ * ```
+ */
+export declare function createTaskId(id: string): TaskId;
+/**
+ * 안건 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 AgendaId
+ * @example
+ * ```typescript
+ * const agendaId = createAgendaId('agenda-001');
+ * // 타입: AgendaId
+ * ```
+ */
+export declare function createAgendaId(id: string): AgendaId;
+/**
+ * 세션 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 SessionId
+ * @example
+ * ```typescript
+ * const sessionId = createSessionId('session-001');
+ * // 타입: SessionId
+ * ```
+ */
+export declare function createSessionId(id: string): SessionId;
+/**
+ * 사실 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 FactId
+ * @example
+ * ```typescript
+ * const factId = createFactId('fact-001');
+ * // 타입: FactId
+ * ```
+ */
+export declare function createFactId(id: string): FactId;
+/**
+ * 추론 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 InferenceId
+ * @example
+ * ```typescript
+ * const inferenceId = createInferenceId('inference-001');
+ * // 타입: InferenceId
+ * ```
+ */
+export declare function createInferenceId(id: string): InferenceId;
+/**
+ * 패턴 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 PatternId
+ * @example
+ * ```typescript
+ * const patternId = createPatternId('pattern-001');
+ * // 타입: PatternId
+ * ```
+ */
+export declare function createPatternId(id: string): PatternId;
+/**
+ * 의견 ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 OpinionId
+ * @example
+ * ```typescript
+ * const opinionId = createOpinionId('opinion-001');
+ * // 타입: OpinionId
+ * ```
+ */
+export declare function createOpinionId(id: string): OpinionId;
+/**
+ * 에이전트 ID 타입 가드
+ * @param value - 확인할 값
+ * @returns AgentId 여부
+ * @example
+ * ```typescript
+ * const value = 'agent-001';
+ * if (isAgentId(value)) {
+ *   // value는 AgentId로 취급됨
+ * }
+ * ```
+ */
+export declare function isAgentId(value: unknown): value is AgentId;
+/**
+ * 작업 ID 타입 가드
+ * @param value - 확인할 값
+ * @returns TaskId 여부
+ * @example
+ * ```typescript
+ * const value = 'task-001';
+ * if (isTaskId(value)) {
+ *   // value는 TaskId로 취급됨
+ * }
+ * ```
+ */
+export declare function isTaskId(value: unknown): value is TaskId;
+/**
+ * 안건 ID 타입 가드
+ * @param value - 확인할 값
+ * @returns AgendaId 여부
+ * @example
+ * ```typescript
+ * const value = 'agenda-001';
+ * if (isAgendaId(value)) {
+ *   // value는 AgendaId로 취급됨
+ * }
+ * ```
+ */
+export declare function isAgendaId(value: unknown): value is AgendaId;
+/**
+ * 세션 ID 타입 가드
+ * @param value - 확인할 값
+ * @returns SessionId 여부
+ * @example
+ * ```typescript
+ * const value = 'session-001';
+ * if (isSessionId(value)) {
+ *   // value는 SessionId로 취급됨
+ * }
+ * ```
+ */
+export declare function isSessionId(value: unknown): value is SessionId;
+/**
+ * 공통 인터페이스
+ */
+/**
+ * 타임스탬프가 포함된 기본 엔티티
+ * @description 생성 및 수정 시간을 추적하는 엔티티
+ */
+export interface Timestamped {
+    /** 생성 시간 */
+    readonly createdAt: Date;
+    /** 마지막 수정 시간 */
+    readonly updatedAt: Date;
+}
+/**
+ * 버전 관리가 포함된 엔티티
+ * @description optimistic locking 및 변경 이력 추적용 버전 필드
+ */
+export interface Versioned {
+    /** 버전 번호 */
+    readonly version: number;
+}
+/**
+ * 식별 가능한 엔티티
+ * @description 고유 ID를 가진 엔티티
+ * @typeParam T - ID 타입 (기본값: string)
+ */
+export interface Identifiable<T extends string = string> {
+    /** 고유 식별자 */
+    readonly id: T;
+}