@obora/runtime 0.1.0

package/dist/blackboard/core/blackboard.d.ts

@@ -0,0 +1,286 @@
+/**
+ * @module blackboard
+ * @description 메인 Blackboard 클래스
+ */
+import type { BlackboardState, BlackboardMeta, BoardPhase, SessionId } from "../types";
+import { VersionConflictError } from "./versioning";
+import { StateSectionAccessor } from "./accessors/state-accessor";
+import { KnowledgeSectionAccessor } from "./accessors/knowledge-accessor";
+import { DecisionsSectionAccessor } from "./accessors/decisions-accessor";
+import { SnapshotManager } from "../snapshot";
+import type { Snapshot, CreateSnapshotOptions, RestoreSnapshotOptions, SnapshotValidationResult } from "../snapshot";
+export { BoardPhase };
+/**
+ * 간단한 EventEmitter 구현
+ */
+type EventListener = (...args: unknown[]) => void;
+declare class SimpleEventEmitter {
+    private _listeners;
+    on(event: string, listener: EventListener): this;
+    off(event: string, listener: EventListener): this;
+    once(event: string, listener: EventListener): this;
+    emit(event: string, ...args: unknown[]): boolean;
+    removeAllListeners(event?: string): this;
+    listenerCount(event: string): number;
+}
+/**
+ * Blackboard 설정 옵션
+ */
+export interface BlackboardOptions {
+    /** 세션 ID (자동 생성되지 않으면 필수) */
+    sessionId?: SessionId;
+    /** 초기 상태 (스냅샷 복원 시 사용) */
+    initialState?: Partial<BlackboardState>;
+    /** 버전 충돌 시 재시도 횟수 */
+    maxRetries?: number;
+    /** 재시도 간격 (ms) */
+    retryDelay?: number;
+    /** 이벤트 리스너 */
+    onEvent?: (event: {
+        type: string;
+        timestamp: Date;
+    }) => void;
+}
+/**
+ * 쿼리 옵션
+ */
+export interface QueryOptions {
+    /** 깊은 복사 반환 여부 (기본: true) */
+    deep?: boolean;
+    /** 필터 조건 */
+    filter?: Record<string, unknown>;
+    /** 정렬 기준 */
+    sort?: {
+        field: string;
+        order: "asc" | "desc";
+    };
+    /** 결과 제한 */
+    limit?: number;
+    /** 오프셋 */
+    offset?: number;
+}
+/**
+ * 쓰기 결과
+ */
+export interface WriteResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** 새 버전 */
+    version: number;
+    /** 변경된 경로 */
+    path: string;
+    /** 이전 값 */
+    previousValue: unknown;
+    /** 에러 (실패 시) */
+    error?: Error;
+}
+/**
+ * 트랜잭션 연산
+ */
+export interface Operation {
+    /** 연산 타입 */
+    type: "read" | "write" | "delete";
+    /** 섹션 */
+    section: string;
+    /** 키/경로 */
+    key: string;
+    /** 값 (write 연산 시) */
+    value?: unknown;
+}
+/**
+ * Blackboard 에러 코드
+ */
+export declare enum BlackboardErrorCode {
+    UNKNOWN_ERROR = 1000,
+    INVALID_INPUT = 1001,
+    NOT_IMPLEMENTED = 1002,
+    PATH_NOT_FOUND = 1003,
+    INVALID_PATH = 1004,
+    SLOT_NOT_FOUND = 2000,
+    SLOT_ALREADY_EXISTS = 2001,
+    SLOT_TYPE_MISMATCH = 2002,
+    SLOT_VERSION_CONFLICT = 2003,
+    ENTRY_NOT_FOUND = 2100,
+    ENTRY_ALREADY_EXISTS = 2101,
+    ENTRY_LOCKED = 2102,
+    AGENT_NOT_FOUND = 3000,
+    AGENT_ALREADY_REGISTERED = 3001,
+    AGENT_NOT_AVAILABLE = 3002,
+    TASK_NOT_FOUND = 3003,
+    TASK_ALREADY_ASSIGNED = 3004,
+    TASK_IN_PROGRESS = 3005,
+    FACT_NOT_FOUND = 4000,
+    INFERENCE_NOT_FOUND = 4001,
+    PATTERN_NOT_FOUND = 4002,
+    INVALID_PREMISES = 4003,
+    AGENDA_NOT_FOUND = 5000,
+    AGENDA_ALREADY_IN_PROGRESS = 5001,
+    AGENDA_ALREADY_RESOLVED = 5002,
+    VOTING_NOT_STARTED = 5003,
+    VOTING_ALREADY_ENDED = 5004,
+    QUORUM_NOT_REACHED = 5005,
+    ALREADY_VOTED = 5006,
+    CONSENSUS_NOT_REACHED = 5007,
+    DUPLICATE_OPINION = 5008,
+    OPINION_NOT_FOUND = 5009,
+    SNAPSHOT_NOT_FOUND = 6000,
+    SNAPSHOT_CORRUPTED = 6001,
+    SNAPSHOT_VERSION_MISMATCH = 6002,
+    EVENT_HANDLER_ERROR = 7000,
+    SUBSCRIPTION_NOT_FOUND = 7001
+}
+/**
+ * 경로 에러
+ */
+export declare class PathNotFoundError extends Error {
+    readonly path: string;
+    readonly code = BlackboardErrorCode.PATH_NOT_FOUND;
+    constructor(path: string);
+}
+/**
+ * Blackboard 에러 클래스
+ */
+export declare class BlackboardError extends Error {
+    readonly code: BlackboardErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(code: BlackboardErrorCode, message: string, details?: unknown | undefined);
+}
+/**
+ * Blackboard 메인 클래스
+ * @description 시스템의 단일 진실 소스(SSOT)를 관리하는 핵심 클래스
+ *
+ * @example
+ * ```typescript
+ * const board = new Blackboard({ sessionId: createSessionId('session-001') });
+ *
+ * // 읽기
+ * const phase = board.read('state.phase');
+ *
+ * // 쓰기 (버전 관리 포함)
+ * const result = board.write('state.phase', 'discussion');
+ *
+ * // 섹션 접근
+ * const stateSection = board.state;
+ * const knowledgeSection = board.knowledge;
+ * const decisionsSection = board.decisions;
+ * ```
+ */
+export declare class Blackboard extends SimpleEventEmitter {
+    private _state;
+    private readonly versionManager;
+    private readonly options;
+    private _snapshotManager;
+    private _stateAccessor?;
+    private _knowledgeAccessor?;
+    private _decisionsAccessor?;
+    constructor(options?: BlackboardOptions);
+    /**
+     * 옵션 정규화
+     */
+    private normalizeOptions;
+    /**
+     * 초기 상태 생성
+     */
+    private createInitialState;
+    /** 메타데이터 섹션 (읽기 전용) */
+    get meta(): Readonly<BlackboardMeta>;
+    /** 상태 섹션 접근자 */
+    get state(): StateSectionAccessor;
+    /** 지식 섹션 접근자 */
+    get knowledge(): KnowledgeSectionAccessor;
+    /** 의사결정 섹션 접근자 */
+    get decisions(): DecisionsSectionAccessor;
+    /** 현재 버전 */
+    get version(): number;
+    /** 세션 ID */
+    get sessionId(): SessionId;
+    /** 스냅샷 관리자 (public) */
+    get snapshotManager(): SnapshotManager;
+    /**
+     * 현재 전체 상태 조회
+     * @returns 현재 Blackboard 상태 (스냅샷용)
+     */
+    getState(): BlackboardState;
+    /**
+     * 경로 기반 읽기
+     * @param path - 점(.)으로 구분된 경로 (예: 'state.phase', 'decisions.current')
+     * @param options - 쿼리 옵션
+     * @returns 해당 경로의 값
+     */
+    read<T = unknown>(path: string, options?: QueryOptions & {
+        strict?: boolean;
+    }): T;
+    /**
+     * 경로 기반 쓰기 (동기)
+     * @param path - 점(.)으로 구분된 경로
+     * @param value - 새 값
+     * @param options - 쓰기 옵션 (expectedVersion 포함)
+     * @returns 쓰기 결과
+     */
+    write(path: string, value: unknown, options?: {
+        expectedVersion?: number;
+    }): WriteResult;
+    /**
+     * 경로 기반 삭제
+     * @param path - 삭제할 경로
+     * @param options - 삭제 옵션
+     * @returns 삭제 결과
+     */
+    delete(path: string, options?: {
+        expectedVersion?: number;
+        strict?: boolean;
+    }): WriteResult;
+    /**
+     * 경로 존재 여부 확인
+     * @param path - 확인할 경로
+     */
+    exists(path: string): boolean;
+    /**
+     * 트랜잭션 실행
+     * @description 여러 쓰기를 원자적으로 실행
+     * @param operations - 실행할 연산 목록
+     * @returns 전체 트랜잭션 결과
+     */
+    transaction(operations: Array<{
+        type: "write" | "delete";
+        path: string;
+        value?: unknown;
+        expectedVersion?: number;
+    }>): WriteResult[];
+    /**
+     * 현재 상태 스냅샷 생성 (비동기)
+     * @param options - 스냅샷 옵션
+     * @returns 스냅샷
+     */
+    createSnapshot(options?: CreateSnapshotOptions): Promise<Snapshot>;
+    /**
+     * 스냅샷에서 상태 복원
+     * @param snapshot - 복원할 스냅샷
+     * @param options - 복원 옵션
+     */
+    restoreSnapshot(snapshot: Snapshot, options?: RestoreSnapshotOptions): void;
+    /**
+     * 스냅샷 검증 (비동기)
+     * @param snapshot - 검증할 스냅샷
+     */
+    validateSnapshot(snapshot: Snapshot): Promise<SnapshotValidationResult>;
+    /**
+     * 전체 상태 교체 (내부용)
+     * @param newState - 새 상태
+     */
+    private replaceState;
+    /**
+     * 스냅샷 생성 (JSON 직렬화용) - 하위 호환성 유지
+     */
+    toJSON(): unknown;
+    /**
+     * 스냅샷에서 복원 - 하위 호환성 유지
+     */
+    static fromJSON(json: {
+        meta?: unknown;
+        state?: unknown;
+        knowledge?: unknown;
+        decisions?: unknown;
+    }): Blackboard;
+}
+export { VersionConflictError };

package/dist/blackboard/core/id-generator.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @module id-generator
+ * @description ID 생성기
+ */
+import type { AgentId, TaskId, AgendaId, SessionId } from "../types";
+/**
+ * ID 생성기 인터페이스
+ */
+export interface IdGenerator {
+    generateAgentId(): AgentId;
+    generateTaskId(): TaskId;
+    generateAgendaId(): AgendaId;
+    generateSessionId(): SessionId;
+    generateGenericId(prefix?: string): string;
+}
+/**
+ * 기본 ID 생성기 (crypto.randomUUID 기반)
+ */
+export declare class DefaultIdGenerator implements IdGenerator {
+    generateAgentId(): AgentId;
+    generateTaskId(): TaskId;
+    generateAgendaId(): AgendaId;
+    generateSessionId(): SessionId;
+    generateGenericId(prefix?: string): string;
+}
+/**
+ * 테스트용 시퀀셜 ID 생성기
+ */
+export declare class SequentialIdGenerator implements IdGenerator {
+    private counters;
+    private nextCounter;
+    generateAgentId(): AgentId;
+    generateTaskId(): TaskId;
+    generateAgendaId(): AgendaId;
+    generateSessionId(): SessionId;
+    generateGenericId(prefix?: string): string;
+    /**
+     * 카운터 리셋 (테스트용)
+     */
+    reset(): void;
+    /**
+     * 특정 프리픽스의 카운터 리셋
+     */
+    resetPrefix(prefix: string): void;
+}
+/**
+ * 기본 ID 생성기 인스턴스 (싱글톤)
+ */
+export declare const defaultIdGenerator: DefaultIdGenerator;
+/**
+ * 테스트용 시퀀셜 ID 생성기 인스턴스
+ */
+export declare const sequentialIdGenerator: SequentialIdGenerator;

package/dist/blackboard/core/immutable.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module immutable
+ * @description 딥 클론 및 불변성 유틸리티
+ */
+/**
+ * 깊은 복사
+ * @param obj - 복사할 객체
+ * @param cloneMap - 순환 참조 추적용 WeakMap (낮은용)
+ * @returns 깊은 복사본
+ */
+export declare function deepClone<T>(obj: T, cloneMap?: WeakMap<object, object>): T;
+/**
+ * 깊은 동결 (불변 객체 생성)
+ * @param obj - 동결할 객체
+ * @returns 동결된 객체
+ */
+export declare function deepFreeze<T>(obj: T): Readonly<T>;
+/**
+ * 불변 업데이트
+ * @description 중첩된 객체를 불변성을 유지하며 업데이트
+ * @param obj - 원본 객체
+ * @param path - 업데이트할 경로
+ * @param updater - 업데이트 함수
+ * @returns 새 객체
+ */
+export declare function immutableUpdate<T>(obj: T, path: string, updater: (value: unknown) => unknown): T;
+/**
+ * Map을 일반 객체로 변환
+ * @param map - 변환할 Map
+ * @returns 일반 객체
+ */
+export declare function mapToObject<K extends string, V>(map: Map<K, V>): Record<K, V>;
+/**
+ * 일반 객체를 Map으로 변환
+ * @param obj - 변환할 객체
+ * @returns Map
+ */
+export declare function objectToMap<K extends string, V>(obj: Record<K, V>): Map<K, V>;
+/**
+ * 객체 병합 (불변)
+ * @param target - 대상 객체
+ * @param sources - 병합할 소스들
+ * @returns 병합된 새 객체
+ */
+export declare function merge<T extends Record<string, unknown>>(target: T, ...sources: Partial<T>[]): T;

package/dist/blackboard/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module core/index
+ * @description Core exports
+ */
+export { Blackboard, BlackboardOptions, QueryOptions, WriteResult, Operation, BlackboardErrorCode, PathNotFoundError, BlackboardError, } from './blackboard';
+export { VersionConflictError } from './versioning';
+export { VersionManager, VersioningConfig, DEFAULT_VERSIONING_CONFIG, } from './versioning';
+export { getByPath, setByPath, deleteByPath, parsePath, isValidPath, normalizePath, joinPath, isSubPath, getParentPath, type ParsedPath, } from './path-utils';
+export { deepClone, deepFreeze, immutableUpdate, mapToObject, objectToMap, merge, } from './immutable';
+export { DefaultIdGenerator, SequentialIdGenerator, defaultIdGenerator, sequentialIdGenerator, type IdGenerator, } from './id-generator';
+export { StateSectionAccessor, KnowledgeSectionAccessor, DecisionsSectionAccessor, } from './accessors';
+export { EventAwareBlackboard, EventAwareBlackboardOptions, } from './blackboard-events';
+export type { TemporalKnowledgeGraph, StagingTKG, ProductionTKG, PromotableProductionTKG, IReflector, } from './tkg';

package/dist/blackboard/core/path-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module path-utils
+ * @description 경로 유틸리티
+ */
+/**
+ * 경로 파싱 결과
+ */
+export interface ParsedPath {
+    /** 섹션 (meta, state, knowledge, decisions) */
+    section: "meta" | "state" | "knowledge" | "decisions";
+    /** 나머지 경로 세그먼트 */
+    segments: string[];
+    /** 전체 경로 */
+    full: string;
+}
+/**
+ * 경로 기반 값 접근
+ * @param obj - 대상 객체
+ * @param path - 점(.)으로 구분된 경로
+ * @returns 해당 경로의 값
+ */
+export declare function getByPath<T = unknown>(obj: unknown, path: string): T | undefined;
+/**
+ * 경로 기반 값 설정 (불변)
+ * @param obj - 대상 객체
+ * @param path - 점(.)으로 구분된 경로
+ * @param value - 설정할 값
+ * @returns 수정된 객체 (불변성 유지)
+ */
+export declare function setByPath<T>(obj: T, path: string, value: unknown): T;
+/**
+ * 경로 기반 값 삭제
+ * @param obj - 대상 객체
+ * @param path - 점(.)으로 구분된 경로
+ * @returns 수정된 객체 (불변성 유지)
+ */
+export declare function deleteByPath<T>(obj: T, path: string): T;
+/**
+ * 경로 파싱
+ * @param path - 전체 경로
+ * @returns 파싱된 경로 정보
+ */
+export declare function parsePath(path: string): ParsedPath;
+/**
+ * 경로 검증
+ * @param path - 검증할 경로
+ * @returns 유효 여부
+ */
+export declare function isValidPath(path: string): boolean;
+/**
+ * 경로 정규화
+ * @param path - 정규화할 경로
+ * @returns 정규화된 경로
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * 경로 결합
+ * @param parts - 결합할 경로들
+ * @returns 결합된 경로
+ */
+export declare function joinPath(...parts: string[]): string;
+/**
+ * 경로가 다른 경로의 하위 경로인지 확인
+ * @param parent - 부모 경로
+ * @param child - 자식 경로
+ * @returns 하위 경로 여부
+ */
+export declare function isSubPath(parent: string, child: string): boolean;
+/**
+ * 경로의 상위 경로 반환
+ * @param path - 경로
+ * @param levels - 올라갈 레벨 수 (기본: 1)
+ * @returns 상위 경로
+ */
+export declare function getParentPath(path: string, levels?: number): string;

package/dist/blackboard/core/tkg.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module core/tkg
+ * @description TKG 인터페이스 계약 (MVP)
+ */
+import type { EdgeId, GraphQuery, IProductionPromotionPort, MergeResult, NodeId, QueryResult, ReflectionOptions, TemporalEdge, TemporalNode, ValidationResult } from '../types/tkg';
+/**
+ * Temporal Knowledge Graph 공통 조회 계약
+ */
+export interface TemporalKnowledgeGraph {
+    readonly nodes: ReadonlyMap<NodeId, TemporalNode>;
+    readonly edges: ReadonlyMap<EdgeId, TemporalEdge>;
+    queryAtTime(query: GraphQuery, time?: Date): QueryResult;
+    queryCurrent(query: GraphQuery): QueryResult;
+    queryTimeRange(query: GraphQuery, from: Date, to: Date): readonly QueryResult[];
+    queryByConfidence(query: GraphQuery, minConfidence: number): QueryResult;
+}
+/**
+ * Observer 전용 Staging 계약 (쓰기 허용)
+ */
+export interface StagingTKG extends TemporalKnowledgeGraph {
+    addNode(node: TemporalNode): NodeId;
+    addEdge(edge: TemporalEdge): EdgeId;
+    validateNode(node: TemporalNode): ValidationResult;
+    validateEdge(edge: TemporalEdge): ValidationResult;
+}
+/**
+ * Reflector 조회 대상 Production 계약 (읽기 전용)
+ *
+ * - 외부 소비자는 ReadonlyMap 뷰만 접근 가능
+ * - 쓰기는 IProductionPromotionPort를 통해서만 허용
+ */
+export interface ProductionTKG extends TemporalKnowledgeGraph {
+    readonly nodes: ReadonlyMap<NodeId, TemporalNode>;
+    readonly edges: ReadonlyMap<EdgeId, TemporalEdge>;
+    getValidNodes(at?: Date): readonly TemporalNode[];
+    getValidEdges(at?: Date): readonly TemporalEdge[];
+}
+/**
+ * Reflector용 조합 타입.
+ *
+ * Production 조회는 ProductionTKG, 변경은 승격 포트로 분리하여
+ * "Production readonly + Promotion Port" 계약을 타입 수준에서 고정합니다.
+ */
+export type PromotableProductionTKG = ProductionTKG & IProductionPromotionPort;
+/**
+ * Reflector 병합 최소 계약
+ */
+export interface IReflector {
+    reflect(source: StagingTKG, target: IProductionPromotionPort, options?: ReflectionOptions): MergeResult;
+}

package/dist/blackboard/core/versioning.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @module versioning
+ * @description 버전 관리 (optimistic locking)
+ */
+/**
+ * 버전 관리 설정
+ */
+export interface VersioningConfig {
+    /** 충돌 시 재시도 횟수 */
+    maxRetries: number;
+    /** 재시도 간격 (ms) */
+    retryDelay: number;
+    /** 지수 백오프 사용 여부 */
+    exponentialBackoff: boolean;
+}
+/**
+ * 기본 버전 관리 설정
+ */
+export declare const DEFAULT_VERSIONING_CONFIG: VersioningConfig;
+/**
+ * 버전 충돌 에러
+ */
+export declare class VersionConflictError extends Error {
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    readonly path: string;
+    constructor(expectedVersion: number, actualVersion: number, path: string);
+}
+/**
+ * Optimistic Locking 관리자
+ * @description 동시 쓰기 충돌을 감지하고 처리
+ */
+export declare class VersionManager {
+    private config;
+    constructor(config?: VersioningConfig);
+    /**
+     * 버전 검증
+     * @param currentVersion - 현재 버전
+     * @param expectedVersion - 예상 버전
+     * @param path - 경로 (에러 메시지용)
+     * @throws {VersionConflictError} 버전 불일치 시
+     */
+    validateVersion(currentVersion: number, expectedVersion: number, path: string): void;
+    /**
+     * 버전 증가
+     * @param currentVersion - 현재 버전
+     * @returns 새 버전
+     */
+    incrementVersion(currentVersion: number): number;
+    /**
+     * 재시도 가능한 쓰기 실행
+     * @param operation - 실행할 쓰기 연산
+     * @param context - 컨텍스트 정보 (로그용)
+     * @returns 최종 결과
+     */
+    executeWithRetry<T>(operation: () => T | Promise<T>, _context?: string): Promise<T>;
+    /**
+     * 재시도 지연 계산
+     * @param attempt - 현재 시도 횟수 (0부터)
+     * @returns 지연 시간 (ms)
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * 지연 (내부 유틸리티)
+     */
+    private sleep;
+    /**
+     * 설정 업데이트
+     * @param partialConfig - 업데이트할 설정 (부분)
+     */
+    updateConfig(partialConfig: Partial<VersioningConfig>): void;
+    /**
+     * 현재 설정 조회
+     */
+    getConfig(): Readonly<VersioningConfig>;
+}
+/**
+ * 기본 버전 관리자 인스턴스
+ */
+export declare const defaultVersionManager: VersionManager;