@obora/runtime 0.1.0

package/dist/blackboard/core/accessors/decisions-accessor.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @module decisions-accessor
+ * @description 의사결정 섹션 접근자
+ */
+import type { Blackboard } from "../blackboard";
+import type { Agenda, AgendaCreateInput, Opinion, OpinionCreateInput, Resolution, DecisionType, OpinionId, AgendaId } from "../../types";
+import type { AgentId } from "../../types";
+import { AgendaStatus } from "../../types";
+/**
+ * 의사결정 섹션 접근자
+ * @description decisions 섹션에 대한 타입 안전한 접근 제공
+ */
+export declare class DecisionsSectionAccessor {
+    private readonly board;
+    constructor(board: Blackboard);
+    /**
+     * 의견 키 생성 (agendaId + agentId 조합)
+     * @private
+     */
+    private getOpinionKey;
+    /**
+     * opinionId로 opinionKey 찾기
+     * @private
+     */
+    private findOpinionKey;
+    /** 현재 안건 */
+    get current(): Agenda | null;
+    /** 대기 중인 안건들 */
+    get pending(): Agenda[];
+    /** 모든 대기 안건 */
+    get allPending(): Agenda[];
+    /** 결정 이력 전체 */
+    get history(): Resolution[];
+    /** 대기 중인 안건 수 */
+    get pendingCount(): number;
+    /** 결정 이력 수 */
+    get historyCount(): number;
+    /**
+     * 안건 제출
+     * @param agendaInput - 새 안건 입력
+     */
+    submitAgenda(agendaInput: AgendaCreateInput): Agenda;
+    /**
+     * 안건 상태 변경
+     */
+    updateAgendaStatus(agendaId: AgendaId, status: AgendaStatus): void;
+    /**
+     * 현재 안건 설정
+     */
+    setCurrentAgenda(agendaId: AgendaId): void;
+    /**
+     * 안건 취소
+     */
+    cancelAgenda(agendaId: AgendaId, reason: string): void;
+    /**
+     * 안건 조회
+     */
+    getAgenda(agendaId: AgendaId): Agenda | undefined;
+    /**
+     * 모든 안건 조회
+     */
+    getAllAgendas(): Agenda[];
+    /**
+     * 의견 제출
+     * @param opinionInput - 의견 생성 입력 (agentId 포함)
+     */
+    submitOpinion(opinionInput: OpinionCreateInput & {
+        agentId: AgentId;
+    }): Opinion;
+    /**
+     * 특정 안건의 모든 의견 조회
+     */
+    getOpinions(agendaId: AgendaId): Opinion[];
+    /**
+     * 에이전트의 의견 조회 (agendaId 먼저)
+     * @deprecated getAgentOpinion() 사용 권장
+     */
+    getOpinionByAgent(agendaId: AgendaId, agentId: AgentId): Opinion | undefined;
+    /**
+     * 에이전트의 의견 조회
+     * @param agentId - 에이전트 ID
+     * @param agendaId - 안건 ID (필수)
+     */
+    getAgentOpinion(agentId: AgentId, agendaId: AgendaId): Opinion | undefined;
+    /**
+     * 의견 요약
+     */
+    summarizeOpinions(agendaId: AgendaId): {
+        total: number;
+        approve: number;
+        reject: number;
+        conditional: number;
+        abstain: number;
+        approvalRate: number;
+        quorumReached: boolean;
+    };
+    /**
+     * 모든 의견 초기화 (재투표 시)
+     */
+    clearOpinions(agendaId: AgendaId): void;
+    /**
+     * 의견 업데이트
+     */
+    updateOpinion(opinionId: OpinionId, updates: Partial<Omit<Opinion, "id" | "createdAt">>): void;
+    /**
+     * 의견 삭제
+     */
+    removeOpinion(opinionId: OpinionId): void;
+    /**
+     * 결정 기록 (안건 제거)
+     * @description 새 결정을 기록하고 관련 안건을 제거합니다.
+     * @warning closeAgenda()를 사용하면 안건이 RESOLVED 상태로 유지됩니다.
+     * 이 메서드는 안건을 완전히 제거합니다.
+     */
+    recordResolution(resolutionInput: Omit<Resolution, "id" | "createdAt" | "updatedAt">): Resolution;
+    /**
+     * 결정 기록 (안건 유지)
+     * @description 안건을 제거하지 않고 결정만 기록합니다.
+     * @private
+     */
+    private recordResolutionKeepAgenda;
+    /**
+     * 결정 이력 조회
+     */
+    getHistory(filter?: {
+        agendaId?: AgendaId;
+        decision?: DecisionType;
+    }): Resolution[];
+    /**
+     * 최근 N개 결정 조회
+     */
+    getRecentResolutions(count: number): Resolution[];
+    /**
+     * 결정 조회
+     */
+    getResolution(resolutionId: string): Resolution | undefined;
+    /**
+     * 안건에 대한 결정 조회
+     */
+    getResolutionByAgenda(agendaId: AgendaId): Resolution | undefined;
+    /**
+     * 결정 수 조회
+     */
+    getResolutionCount(): number;
+    /**
+     * 안건 수 조회
+     */
+    getAgendaCount(): number;
+    /**
+     * 의견 수 조회
+     */
+    getOpinionCount(): number;
+    /**
+     * 투표 결과 확인
+     * @note conditional은 승인으로 카운트됩니다 (찬성 = approve + conditional)
+     */
+    checkVotingResult(agendaId: AgendaId): {
+        passed: boolean;
+        method: "majority" | "unanimous" | "weighted" | "supermajority";
+        summary: {
+            total: number;
+            approve: number;
+            reject: number;
+            conditional: number;
+            abstain: number;
+            approvalRate: number;
+            quorumReached: boolean;
+        };
+    };
+    /**
+     * 안건 종료 (결정 기록)
+     * @description 안건을 RESOLVED 상태로 변경하고 결정을 기록합니다.
+     *
+     * **정책:** 안건은 RESOLVED 상태로 변경 후에도 pending/current에 유지됩니다.
+     * 이는 결정 이력 추적 및 후속 조치 관리를 위함입니다.
+     * 안건을 완전히 제거하려면 {@link recordResolution()}을 직접 호출하세요.
+     *
+     * @param agendaId - 종료할 안건 ID
+     * @param decision - 결정 유형 (기본: approved)
+     */
+    closeAgenda(agendaId: AgendaId, decision?: "approved" | "rejected" | "deferred"): void;
+    /**
+     * 안건 업데이트
+     */
+    updateAgenda(agendaId: AgendaId, updates: Partial<Omit<Agenda, "id" | "createdAt">>): Agenda;
+    /**
+     * 모든 결정 초기화
+     */
+    clearAll(): void;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * @module accessors/index
+ * @description 섹션 접근자 exports
+ */
+export { StateSectionAccessor } from './state-accessor';
+export { KnowledgeSectionAccessor } from './knowledge-accessor';
+export { DecisionsSectionAccessor } from './decisions-accessor';

package/dist/blackboard/core/accessors/knowledge-accessor.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @module knowledge-accessor
+ * @description 지식 섹션 접근자
+ */
+import type { Blackboard } from '../blackboard';
+import type { Fact, FactCreateInput, Inference, InferenceCreateInput, Pattern, PatternCreateInput, KnowledgeQuery, InferenceQuery, PatternQuery } from '../../types';
+import type { AgentId } from '../../types';
+/**
+ * 지식 섹션 접근자
+ * @description knowledge 섹션에 대한 타입 안전한 접근 제공
+ */
+export declare class KnowledgeSectionAccessor {
+    private readonly board;
+    constructor(board: Blackboard);
+    /**
+     * confidence 값 검증
+     * @private
+     */
+    private validateConfidence;
+    /**
+     * 전체 사실 목록
+     */
+    get facts(): Fact[];
+    /**
+     * 전체 추론 목록
+     */
+    get inferences(): Inference[];
+    /**
+     * 전체 패턴 목록
+     */
+    get patterns(): Pattern[];
+    /**
+     * 사실 수
+     */
+    get factCount(): number;
+    /**
+     * 추론 수
+     */
+    get inferenceCount(): number;
+    /**
+     * 패턴 수
+     */
+    get patternCount(): number;
+    /**
+     * 사실 추가
+     * @param factInput - 새 사실 입력
+     */
+    addFact(factInput: FactCreateInput): Fact;
+    /**
+     * 사실 조회
+     */
+    getFact(factId: string): Fact | undefined;
+    /**
+     * 사실 업데이트
+     */
+    updateFact(factId: string, updates: Partial<Omit<Fact, 'id' | 'createdAt'>>): Fact | undefined;
+    /**
+     * 사실 검색
+     */
+    findFacts(query: KnowledgeQuery): Fact[];
+    /**
+     * 만료된 사실 정리
+     */
+    cleanupExpiredFacts(): number;
+    /**
+     * 사실 삭제
+     */
+    removeFact(factId: string): void;
+    /**
+     * 사실 수 조회 (deprecated: factCount getter 사용)
+     */
+    getFactCount(): number;
+    /**
+     * 추론 추가
+     */
+    addInference(inferenceInput: InferenceCreateInput): Inference;
+    /**
+     * 추론 조회
+     */
+    getInference(inferenceId: string): Inference | undefined;
+    /**
+     * 추론 업데이트
+     */
+    updateInference(inferenceId: string, updates: Partial<Omit<Inference, 'id' | 'createdAt'>>): Inference | undefined;
+    /**
+     * 추론 검색
+     */
+    findInferences(query: InferenceQuery): Inference[];
+    /**
+     * 특정 사실을 전제로 하는 추론 찾기
+     */
+    findInferencesByPremise(factId: string): Inference[];
+    /**
+     * 에이전트별 추론 조회
+     */
+    findInferencesByAgent(agentId: AgentId): Inference[];
+    /**
+     * 추론 삭제
+     */
+    removeInference(inferenceId: string): void;
+    /**
+     * 추론 수 조회 (deprecated: inferenceCount getter 사용)
+     */
+    getInferenceCount(): number;
+    /**
+     * 패턴 추가
+     */
+    addPattern(patternInput: PatternCreateInput): Pattern;
+    /**
+     * 패턴 추가/업데이트
+     */
+    upsertPattern(patternInput: PatternCreateInput): Pattern;
+    /**
+     * 패턴 조회
+     */
+    getPattern(patternId: string): Pattern | undefined;
+    /**
+     * 패턴 업데이트
+     */
+    updatePattern(patternId: string, updates: Partial<Omit<Pattern, 'id' | 'createdAt'>>): Pattern | undefined;
+    /**
+     * 패턴 검색
+     */
+    findPatterns(query: PatternQuery): Pattern[];
+    /**
+     * 에이전트가 발견한 패턴 조회
+     */
+    findPatternsByAgent(agentId: AgentId): Pattern[];
+    /**
+     * 패턴 사용 기록
+     */
+    recordPatternUsage(patternId: string, success: boolean): void;
+    /**
+     * 패턴 삭제
+     */
+    removePattern(patternId: string): void;
+    /**
+     * 패턴 수 조회 (deprecated: patternCount getter 사용)
+     */
+    getPatternCount(): number;
+    /**
+     * 모든 지식 초기화
+     */
+    clearAll(): void;
+    /**
+     * 지식 섹션 통계
+     */
+    getStats(): {
+        facts: number;
+        inferences: number;
+        patterns: number;
+        expiredFacts: number;
+    };
+}

package/dist/blackboard/core/accessors/state-accessor.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @module state-accessor
+ * @description 상태 섹션 접근자
+ */
+import type { Blackboard } from "../blackboard";
+import type { BoardPhase } from "../../types";
+import type { AgentStatus, AgentRole } from "../../types";
+import { AgentStatusEnum } from "../../types";
+import type { Task, TaskId, TaskError } from "../../types";
+import { TaskStatus, TaskPriority } from "../../types";
+import type { AgentId } from "../../types";
+/**
+ * 상태 섹션 접근자
+ * @description state 섹션에 대한 타입 안전한 접근 제공
+ */
+export declare class StateSectionAccessor {
+    private readonly board;
+    constructor(board: Blackboard);
+    /** 현재 단계 */
+    get phase(): BoardPhase;
+    set phase(value: BoardPhase);
+    /** 컨텍스트 데이터 */
+    get context(): Record<string, unknown>;
+    setContext(key: string, value: unknown): void;
+    /**
+     * 컨텍스트 값 조회 (기본값 포함)
+     */
+    getContext<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * 컨텍스트 값 조회 (기본값 포함) - 별칭 메서드
+     */
+    getContextValue<T>(key: string, defaultValue?: T): T | undefined;
+    /**
+     * 컨텍스트 항목 삭제
+     */
+    deleteContext(key: string): void;
+    /**
+     * 컨텍스트 병합
+     */
+    mergeContext(partial: Record<string, unknown>): void;
+    /**
+     * 컨텍스트 초기화
+     */
+    clearContext(): void;
+    /**
+     * 에이전트 등록
+     * @param agent - 에이전트 상태 정보
+     */
+    registerAgent(agent: AgentStatus): void;
+    /**
+     * 에이전트 상태 업데이트
+     * @param agentId - 에이전트 ID
+     * @param updates - 업데이트할 필드
+     */
+    updateAgent(agentId: AgentId, updates: Partial<AgentStatus>): void;
+    /**
+     * 에이전트 제거
+     * @param agentId - 에이전트 ID
+     */
+    removeAgent(agentId: AgentId): void;
+    /**
+     * 에이전트 조회
+     * @param agentId - 에이전트 ID
+     */
+    getAgent(agentId: AgentId): AgentStatus | undefined;
+    /**
+     * 모든 에이전트 조회
+     * @param filter - 필터 조건
+     */
+    getAgents(filter?: {
+        role?: AgentRole;
+        status?: AgentStatusEnum;
+    }): AgentStatus[];
+    /**
+     * 에이전트 수 조회 (getter)
+     */
+    get agentCount(): number;
+    /**
+     * 에이전트 수 조회 (호환성 메서드)
+     */
+    getAgentCount(): number;
+    /**
+     * 에이전트 존재 여부 확인
+     */
+    hasAgent(id: AgentId): boolean;
+    /**
+     * 에이전트 하트비트 업데이트
+     */
+    updateAgentHeartbeat(id: AgentId): void;
+    /**
+     * 활성 에이전트 수 조회 (BUSY 상태 에이전트)
+     * @description 현재 작업을 수행 중인(BUSY 상태) 에이전트의 수를 반환합니다.
+     * @deprecated 이름이 혼동스러울 수 있으므로 {@link getBusyAgentCount()} 사용 권장
+     */
+    getActiveAgentCount(): number;
+    /**
+     * BUSY 상태 에이전트 수 조회
+     * @description 현재 작업을 수행 중인(BUSY 상태) 에이전트의 수를 반환합니다.
+     */
+    getBusyAgentCount(): number;
+    /**
+     * 작업 추가
+     */
+    addTask(task: Task): void;
+    /**
+     * 작업 업데이트
+     */
+    updateTask(taskId: TaskId, updates: Partial<Task>): void;
+    /**
+     * 작업 조회
+     */
+    getTask(taskId: TaskId): Task | undefined;
+    /**
+     * 작업 목록 조회
+     */
+    getTasks(filter?: {
+        status?: TaskStatus;
+        assignedTo?: AgentId;
+        priority?: TaskPriority;
+    }): Task[];
+    /**
+     * 작업 삭제
+     */
+    removeTask(taskId: TaskId): void;
+    /**
+     * 다음 실행 가능한 작업들
+     * @param completedTasks - 완료된 작업 ID 목록
+     */
+    getNextTasks(completedTasks?: Set<TaskId>): Task[];
+    /**
+     * 에이전트의 현재 작업 조회
+     */
+    getAgentCurrentTask(agentId: AgentId): Task | undefined;
+    /**
+     * 작업 수 조회 (getter)
+     */
+    get taskCount(): number;
+    /**
+     * 작업 수 조회 (호환성 메서드)
+     */
+    getTaskCount(): number;
+    /**
+     * 작업 존재 여부 확인
+     */
+    hasTask(id: TaskId): boolean;
+    /**
+     * 작업 할당
+     * @description 에이전트 존재 여부와 상태를 검증 후 작업을 할당합니다.
+     * @param taskId - 할당할 작업 ID
+     * @param agentId - 할당받을 에이전트 ID
+     */
+    assignTask(taskId: TaskId, agentId: AgentId): void;
+    /**
+     * 작업 할당 해제
+     */
+    unassignTask(taskId: TaskId): void;
+    /**
+     * 작업 완료 처리
+     */
+    completeTask(taskId: TaskId, outputs: Record<string, unknown>): void;
+    /**
+     * 작업 실패 처리
+     */
+    failTask(taskId: TaskId, error: TaskError): void;
+    /**
+     * 실행 중인 작업 수 조회
+     */
+    getRunningTaskCount(): number;
+    /**
+     * 대기 중인 작업 수 조회
+     */
+    getPendingTaskCount(): number;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * @module blackboard-events
+ * @description EventAwareBlackboard - 이벤트 발행 기능이 통합된 Blackboard
+ */
+import { Blackboard, type BlackboardOptions } from "./blackboard";
+import { EventBus, type EventBusOptions } from "../events/event-bus";
+import { EventFactory } from "../events/event-factory";
+import type { Event as BBEvent } from "../events/types";
+import type { AgentStatus, Task, Agenda, OpinionCreateInput, Resolution, Fact, Inference, Pattern, BoardPhase, AgentId, TaskId, AgendaId, FactCreateInput, InferenceCreateInput, PatternCreateInput, AgendaCreateInput } from "../types";
+/**
+ * 이벤트 발행 기능이 통합된 Blackboard 옵션
+ */
+export interface EventAwareBlackboardOptions extends BlackboardOptions {
+    /** Event Bus 옵션 */
+    eventBusOptions?: EventBusOptions;
+    /** 자동 이벤트 발행 활성화 여부 (기본: true) */
+    autoEmitEvents?: boolean;
+    /** 이벤트 발행 실패 시 throw 여부 (기본: false) */
+    throwOnEventError?: boolean;
+}
+/**
+ * 이벤트 발행 기능이 통합된 Blackboard
+ * @description Blackboard의 상태 변경 시 자동으로 이벤트 발행
+ *
+ * @example
+ * ```typescript
+ * import { EventAwareBlackboard, createSessionId, createAgentId } from '@obora-kit/blackboard';
+ *
+ * const board = new EventAwareBlackboard({
+ *   sessionId: createSessionId('session-001'),
+ *   eventBusOptions: { historySize: 1000 },
+ * });
+ *
+ * // 작업 관련 모든 이벤트 구독 (와일드카드)
+ * board.events.subscribe('task.*', (event) => {
+ *   console.log(`Task event: ${event.type}`);
+ * });
+ *
+ * // 특정 이벤트 구독
+ * board.events.subscribe('decision.consensus.reached', (event) => {
+ *   console.log(`Consensus reached`);
+ * });
+ *
+ * // 상태 변경 시 자동으로 이벤트 발행됨
+ * board.setPhase('discussion'); // → PhaseChangedEvent 발행
+ * board.submitAgenda({...}); // → AgendaSubmittedEvent 발행
+ * ```
+ */
+export declare class EventAwareBlackboard extends Blackboard {
+    /** Event Bus 인스턴스 */
+    readonly events: EventBus;
+    /** Event Factory 인스턴스 */
+    readonly eventFactory: EventFactory;
+    private _autoEmitEvents;
+    private readonly _throwOnEventError;
+    constructor(options?: EventAwareBlackboardOptions);
+    private generateEventId;
+    private emitEvent;
+    /** 자동 이벤트 발행 활성화/비활성화 */
+    setAutoEmit(enabled: boolean): void;
+    /** 수동 이벤트 발행 */
+    emitCustomEvent<T extends BBEvent>(event: T): void;
+    /** 수동 비동기 이벤트 발행 */
+    emitCustomEventAsync<T extends BBEvent>(event: T): Promise<void>;
+    /** 단계 설정 */
+    setPhase(newPhase: BoardPhase): void;
+    /** 컨텍스트 설정 */
+    setContext(key: string, value: unknown): void;
+    /** 에이전트 등록 */
+    registerAgent(agent: AgentStatus): void;
+    /** 에이전트 업데이트 */
+    updateAgent(agentId: AgentId, updates: Partial<AgentStatus>): void;
+    /** 에이전트 제거 */
+    removeAgent(agentId: AgentId, reason?: string): void;
+    /** 작업 추가 */
+    addTask(task: Task): void;
+    /** 작업 업데이트 */
+    updateTask(taskId: TaskId, updates: Partial<Task>): void;
+    /** 사실 추가 */
+    addFact(factInput: FactCreateInput): Fact;
+    /** 추론 추가 */
+    addInference(inferenceInput: InferenceCreateInput): Inference;
+    /** 패턴 추가/업데이트 */
+    upsertPattern(patternInput: PatternCreateInput): Pattern;
+    /** 안건 제출 */
+    submitAgenda(agendaInput: AgendaCreateInput): Agenda;
+    /** 현재 안건 설정 */
+    setCurrentAgenda(agendaId: AgendaId): void;
+    /** 안건 취소 */
+    cancelAgenda(agendaId: AgendaId, reason: string): void;
+    /** 의견 제출 */
+    submitOpinion(opinionInput: OpinionCreateInput & {
+        agentId: AgentId;
+    }): void;
+    /** 결정 기록 */
+    recordResolution(resolutionInput: Omit<Resolution, "id" | "createdAt" | "updatedAt">): Resolution;
+    /** 스냅샷 생성 이벤트 발행 */
+    emitSnapshotCreated(snapshotId: string): void;
+    /** 스냅샷 복원 이벤트 발행 */
+    emitSnapshotRestored(snapshotId: string): void;
+    /** 시스템 에러 이벤트 발행 */
+    emitSystemError(code: string, message: string, details?: unknown): void;
+    /** 버전 충돌 이벤트 발행 */
+    emitVersionConflict(path: string, expectedVersion: number, actualVersion: number): void;
+}