@obora/runtime 0.1.0

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

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

@@ -0,0 +1,217 @@
+/**
+ * @module blackboard
+ * @description Blackboard 상태 스키마 정의 - 전체 시스템 상태
+ */
+import type { AgentId, TaskId, SessionId } from './base';
+import type { AgentStatus } from './agent';
+import type { Task } from './task';
+import type { Agenda, Opinion, Resolution } from './decision';
+import type { Fact, Inference, Pattern } from './knowledge';
+/**
+ * 이사회 회의 단계
+ * @description 이사회(Blackboard)의 현재 진행 단계
+ */
+export type BoardPhase = 'idle' | 'agenda_setting' | 'discussion' | 'debate' | 'voting' | 'resolved';
+/**
+ * Blackboard 메타데이터
+ * @description Blackboard 상태의 메타데이터
+ */
+export interface BlackboardMeta {
+    /** 상태 버전 (optimistic locking용) */
+    version: number;
+    /** 마지막 업데이트 시간 */
+    lastUpdated: Date;
+    /** 현재 세션 ID */
+    sessionId: SessionId;
+    /** 생성 시간 */
+    createdAt: Date;
+}
+/**
+ * 상태 섹션
+ * @description 현재 시스템 상태를 담는 섹션
+ */
+export interface StateSection {
+    /** 현재 단계 */
+    phase: BoardPhase;
+    /** 컨텍스트 데이터 */
+    context: Record<string, unknown>;
+    /** 에이전트 상태 맵 */
+    agents: Map<AgentId, AgentStatus>;
+    /** 작업 맵 */
+    tasks: Map<TaskId, Task>;
+}
+/**
+ * 지식 섹션
+ * @description 축적된 지식을 담는 섹션
+ */
+export interface KnowledgeSection {
+    /** 사실 목록 */
+    facts: Fact[];
+    /** 추론 목록 */
+    inferences: Inference[];
+    /** 패턴 목록 */
+    patterns: Pattern[];
+}
+/**
+ * 의사결정 섹션
+ * @description 안건 및 결정을 담는 섹션
+ */
+export interface DecisionsSection {
+    /** 현재 논의 중인 안건 */
+    current: Agenda | null;
+    /** 대기 중인 안건들 */
+    pending: Agenda[];
+    /** 의견 맵 (키: agendaId:agentId) */
+    opinions: Map<string, Opinion>;
+    /** 결정 이력 */
+    history: Resolution[];
+    /** 투표 세션 맵 (키: sessionId 또는 agendaId) */
+    voting: Record<string, VotingSession>;
+}
+/**
+ * 투표 세션
+ * @description DirectorAgent.startVotingSession/tallyVotes 지원
+ */
+export interface VotingSession {
+    /** 시작 시간 */
+    started: Date;
+    /** 참여자 목록 */
+    participants: string[];
+    /** 투표 기록 */
+    votes: Record<string, unknown>;
+    /** 세션 상태 */
+    status: 'in-progress' | 'completed' | 'cancelled';
+}
+/**
+ * 전체 Blackboard 상태
+ * @description 시스템의 단일 진실 소스 (SSOT)
+ *
+ * @example
+ * ```typescript
+ * import { createSessionId } from './base';
+ *
+ * const blackboardState: BlackboardState = {
+ *   meta: {
+ *     version: 1,
+ *     lastUpdated: new Date(),
+ *     sessionId: createSessionId('session-001'),
+ *     createdAt: new Date(),
+ *   },
+ *   state: {
+ *     phase: 'idle',
+ *     context: {},
+ *     agents: new Map(),
+ *     tasks: new Map(),
+ *   },
+ *   knowledge: {
+ *     facts: [],
+ *     inferences: [],
+ *     patterns: [],
+ *   },
+ *   decisions: {
+ *     current: null,
+ *     pending: [],
+ *     opinions: new Map(),
+ *     history: [],
+ *   },
+ * };
+ * ```
+ */
+export interface BlackboardState {
+    /** 메타데이터 */
+    meta: BlackboardMeta;
+    /** 상태 섹션 */
+    state: StateSection;
+    /** 지식 섹션 */
+    knowledge: KnowledgeSection;
+    /** 의사결정 섹션 */
+    decisions: DecisionsSection;
+}
+/**
+ * Blackboard 초기 상태 생성 옵션
+ * @description 새 Blackboard 인스턴스 생성 시 필요한 옵션
+ */
+export interface BlackboardCreateOptions {
+    /** 세션 ID (없으면 자동 생성) */
+    sessionId?: SessionId;
+    /** 초기 단계 (기본: idle) */
+    initialPhase?: BoardPhase;
+    /** 초기 컨텍스트 데이터 */
+    initialContext?: Record<string, unknown>;
+}
+/**
+ * 상태 업데이트 요청
+ * @description Blackboard 상태 업데이트를 위한 요청
+ */
+export interface StateUpdateRequest {
+    /** 업데이트할 섹션 */
+    section: 'state' | 'knowledge' | 'decisions';
+    /** 업데이트 유형 */
+    type: 'create' | 'update' | 'delete';
+    /** 업데이트할 경로 */
+    path: string;
+    /** 새 데이터 (create/update 시) */
+    data?: unknown;
+    /** 기대 버전 (optimistic locking용) */
+    expectedVersion?: number;
+}
+/**
+ * 상태 업데이트 결과
+ * @description 상태 업데이트 작업의 결과
+ */
+export interface StateUpdateResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** 새 버전 */
+    version: number;
+    /** 업데이트 시간 */
+    updatedAt: Date;
+    /** 에러 정보 (실패 시) */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Blackboard 이벤트 타입
+ * @description Blackboard에서 발생하는 이벤트의 종류
+ */
+export type BlackboardEventType = 'phase_changed' | 'agent_joined' | 'agent_left' | 'agent_status_changed' | 'task_created' | 'task_updated' | 'task_completed' | 'agenda_submitted' | 'agenda_updated' | 'opinion_added' | 'resolution_created';
+/**
+ * Blackboard 이벤트
+ * @description Blackboard에서 발생하는 이벤트 정보
+ */
+export interface BlackboardEvent {
+    /** 이벤트 타입 */
+    type: BlackboardEventType;
+    /** 이벤트 발생 시간 */
+    timestamp: Date;
+    /** 이벤트 데이터 */
+    data: unknown;
+    /** 관련 엔티티 ID (있는 경우) */
+    entityId?: string;
+}
+/**
+ * Blackboard 통계
+ * @description Blackboard의 현재 상태 통계
+ */
+export interface BlackboardStats {
+    /** 현재 단계 */
+    phase: BoardPhase;
+    /** 참여 중인 에이전트 수 */
+    activeAgents: number;
+    /** 총 작업 수 */
+    totalTasks: number;
+    /** 실행 중인 작업 수 */
+    runningTasks: number;
+    /** 대기 중인 안건 수 */
+    pendingAgendas: number;
+    /** 총 사실 수 */
+    totalFacts: number;
+    /** 총 추론 수 */
+    totalInferences: number;
+    /** 총 패턴 수 */
+    totalPatterns: number;
+    /** 총 결정 수 */
+    totalResolutions: number;
+}

package/dist/blackboard/types/decision.d.ts

@@ -0,0 +1,260 @@
+/**
+ * @module decision
+ * @description 의사결정 관련 타입 정의 - Agenda, Opinion, Resolution
+ */
+import type { Identifiable, Timestamped, Versioned } from "./base";
+import type { AgentId, AgendaId, OpinionId } from "./base";
+/**
+ * 투표 방식
+ * @description 안건 결정을 위한 투표 방식
+ */
+export type VotingMethod = "majority" | "unanimous" | "weighted" | "supermajority";
+/**
+ * 안건 상태
+ * @description 안건의 현재 진행 상태
+ */
+export declare enum AgendaStatus {
+    /** 초안 - 아직 제출되지 않음 */
+    DRAFT = "draft",
+    /** 제출됨 - 논의 대기 */
+    SUBMITTED = "submitted",
+    /** 논의 중 */
+    DISCUSSING = "discussing",
+    /** 토론 중 */
+    DEBATING = "debating",
+    /** 투표 중 */
+    VOTING = "voting",
+    /** 결정됨 */
+    RESOLVED = "resolved",
+    /** 연기됨 */
+    DEFERRED = "deferred",
+    /** 취소됨 */
+    CANCELLED = "cancelled"
+}
+/**
+ * 입장 (스탠스)
+ * @description 의견 제출자의 입장
+ */
+export type Stance = "approve" | "reject" | "conditional" | "abstain";
+/**
+ * 최종 결정 유형
+ * @description 안건에 대한 최종 결정의 유형
+ */
+export type DecisionType = "approved" | "rejected" | "deferred" | "amended";
+/**
+ * 첨부 자료
+ * @description 안건에 첨부된 문서, 데이터 등
+ */
+export interface Attachment {
+    /** 파일명 */
+    name: string;
+    /** MIME 타입 */
+    mimeType: string;
+    /** URL 또는 데이터 참조 */
+    url: string;
+    /** 크기 (바이트) */
+    size: number;
+}
+/**
+ * 안건 (의제)
+ * @description AI 이사회에서 논의할 주제
+ *
+ * @example
+ * ```typescript
+ * const agenda: Agenda = {
+ *   id: createAgendaId('agenda-001'),
+ *   title: '신규 서비스 출시 검토',
+ *   description: 'Q2에 출시 예정인 신규 서비스의 적합성 검토',
+ *   proposer: createAgentId('ceo-agent'),
+ *   status: AgendaStatus.SUBMITTED,
+ *   deadline: new Date('2026-02-10'),
+ *   requiredQuorum: 3,
+ *   votingMethod: 'majority',
+ *   priority: 1,
+ *   tags: ['business', 'strategy'],
+ *   attachments: [],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   version: 1,
+ * };
+ * ```
+ */
+export interface Agenda extends Identifiable<AgendaId>, Timestamped, Versioned {
+    /** 안건 제목 */
+    title: string;
+    /** 안건 상세 설명 */
+    description: string;
+    /** 제안자 에이전트 ID */
+    proposer: AgentId;
+    /** 현재 상태 */
+    status: AgendaStatus;
+    /** 마감 기한 (선택) */
+    deadline: Date | null;
+    /** 필요 정족수 */
+    requiredQuorum: number;
+    /** 투표 방식 */
+    votingMethod: VotingMethod;
+    /** 우선순위 (0-10, 높을수록 중요) */
+    priority: number;
+    /** 태그 */
+    tags: string[];
+    /** 첨부 자료 */
+    attachments: Attachment[];
+}
+/**
+ * 의견
+ * @description 에이전트가 안건에 대해 제출하는 의견
+ *
+ * @example
+ * ```typescript
+ * const opinion: Opinion = {
+ *   id: createOpinionId('opinion-001'),
+ *   agentId: createAgentId('agent-001'),
+ *   agendaId: createAgendaId('agenda-001'),
+ *   stance: 'approve',
+ *   reason: '시장 조사 결과가 긍정적임',
+ *   conditions: ['마케팅 예산 확보 필요'],
+ *   confidence: 0.85,
+ *   references: ['fact-001', 'inference-002'],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Opinion extends Identifiable<OpinionId>, Timestamped {
+    /** 의견 제출자 */
+    agentId: AgentId;
+    /** 관련 안건 ID */
+    agendaId: AgendaId;
+    /** 입장 */
+    stance: Stance;
+    /** 의견 내용 (근거) */
+    reason: string;
+    /** 조건 (conditional일 경우) */
+    conditions: string[];
+    /** 확신도 (0.0 - 1.0) */
+    confidence: number;
+    /** 참조한 사실/추론 ID 목록 */
+    references: string[];
+}
+/**
+ * 투표 요약
+ * @description 투표 결과의 요약 통계
+ */
+export interface VoteSummary {
+    /** 찬성 수 */
+    approve: number;
+    /** 반대 수 */
+    reject: number;
+    /** 기권 수 */
+    abstain: number;
+    /** 조건부 찬성 수 */
+    conditional: number;
+    /** 총 투표 수 */
+    total: number;
+}
+/**
+ * 다음 단계 행동
+ * @description 결정 후 이행할 행동 항목
+ */
+export interface NextAction {
+    /** 행동 설명 */
+    description: string;
+    /** 담당자 */
+    assignee: AgentId | null;
+    /** 기한 */
+    dueDate: Date | null;
+}
+/**
+ * 결정 (해결)
+ * @description 안건에 대한 최종 결정 기록
+ *
+ * @example
+ * ```typescript
+ * const resolution: Resolution = {
+ *   id: 'res-001',
+ *   agendaId: createAgendaId('agenda-001'),
+ *   decision: 'approved',
+ *   summary: '신규 서비스 출시 승인',
+ *   voteSummary: {
+ *     approve: 3,
+ *     reject: 1,
+ *     abstain: 0,
+ *     conditional: 0,
+ *     total: 4,
+ *   },
+ *   conditions: ['Q2 내 출시'],
+ *   dissent: ['보안 검토 필요'],
+ *   decidedBy: createAgentId('director-agent'),
+ *   nextActions: [
+ *     {
+ *       description: '출시 계획 수립',
+ *       assignee: createAgentId('pm-agent'),
+ *       dueDate: new Date('2026-02-15'),
+ *     },
+ *   ],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ * };
+ * ```
+ */
+export interface Resolution extends Identifiable, Timestamped {
+    /** 관련 안건 ID */
+    agendaId: AgendaId;
+    /** 결정 유형 */
+    decision: DecisionType;
+    /** 결정 요약 */
+    summary: string;
+    /** 투표 결과 요약 */
+    voteSummary: VoteSummary;
+    /** 이행 조건 (있는 경우) */
+    conditions: string[];
+    /** 반대 의견 요약 (있는 경우) */
+    dissent: string[];
+    /** 결정 주체 (director) */
+    decidedBy: AgentId;
+    /** 다음 단계 행동 */
+    nextActions: NextAction[];
+}
+/**
+ * 안건 생성 옵션
+ * @description 새 안건 생성 시 필요한 필드
+ */
+export interface AgendaCreateInput {
+    /** 안건 제목 */
+    title: string;
+    /** 안건 상세 설명 */
+    description: string;
+    /** 제안자 에이전트 ID */
+    proposer: AgentId;
+    /** 마감 기한 (선택) */
+    deadline?: Date | null;
+    /** 필요 정족수 (기본: 3) */
+    requiredQuorum?: number;
+    /** 투표 방식 (기본: majority) */
+    votingMethod?: VotingMethod;
+    /** 우선순위 (기본: 1) */
+    priority?: number;
+    /** 태그 */
+    tags?: string[];
+    /** 첨부 자료 */
+    attachments?: Attachment[];
+}
+/**
+ * 의견 생성 옵션
+ * @description 새 의견 제출 시 필요한 필드
+ */
+export interface OpinionCreateInput {
+    /** 관련 안건 ID */
+    agendaId: AgendaId;
+    /** 입장 */
+    stance: Stance;
+    /** 의견 내용 (근거) */
+    reason: string;
+    /** 조건 (conditional일 경우) */
+    conditions?: string[];
+    /** 확신도 (기본: 1.0) */
+    confidence?: number;
+    /** 참조한 사실/추론 ID 목록 */
+    references?: string[];
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @module index
+ * @description 메인 export - 모든 타입의 진입점
+ */
+export * from './base';
+export * from './agent';
+export * from './task';
+export * from './decision';
+export * from './knowledge';
+export * from './message';
+export * from './blackboard';
+export * from './tkg';