@obora/runtime 0.1.0

package/dist/_legacy/actor/types/actor.d.ts

@@ -0,0 +1,251 @@
+/**
+ * @module actor
+ * @description Actor 타입 정의 - 액터의 기본 인터페이스와 상태 관리
+ */
+import type { Action } from "./action";
+import type { IBlackboard } from "./blackboard";
+import type { Message } from "./message";
+import type { IMessageBus } from "./message";
+import type { ActorMetrics } from "./metrics";
+import type { Observation } from "./observation";
+import type { Result } from "./result";
+/**
+ * Actor 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ *
+ * 형식: `<role>-<uuid>`
+ * 예: analyst-550e8400-e29b-41d4-a716-446655440000
+ */
+export type ActorId = string & {
+    readonly __brand: "ActorId";
+};
+/**
+ * Task 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+export type TaskId = string & {
+    readonly __brand: "TaskId";
+};
+/**
+ * Actor 역할 타입
+ * @description 액터가 수행하는 역할을 정의
+ */
+export type ActorRole = "analyst" | "executor" | "verifier" | "director";
+/**
+ * Actor 역할 설명
+ * @description 각 역할의 설명 정의
+ */
+export declare const ActorRoleDescription: Record<ActorRole, string>;
+/**
+ * Actor 역할별 권한 레벨
+ * @description 각 역할의 권한 레벨 정의
+ */
+export declare const ActorRoleLevel: Record<ActorRole, number>;
+/**
+ * Actor 생명주기 상태 열거형
+ * @description 액터의 현재 실행 상태를 나타냄
+ */
+export declare enum ActorLifecycleStatus {
+    /** 생성됨 - 초기화 완료, 시작 대기 */
+    CREATED = "created",
+    /** 시작 중 - 초기화 및 리소스 로딩 중 */
+    STARTING = "starting",
+    /** 실행 중 - 정상적으로 동작 중 */
+    RUNNING = "running",
+    /** 유휴 상태 - 대기 중, 작업 수행 가능 */
+    IDLE = "idle",
+    /** 바쁨 - 현재 작업 수행 중 */
+    BUSY = "busy",
+    /** 중지 중 - 종료 처리 중 */
+    STOPPING = "stopping",
+    /** 중지됨 - 완전히 종료됨 */
+    STOPPED = "stopped",
+    /** 재시작 중 - 재시작 처리 중 */
+    RESTARTING = "restarting",
+    /** 오류 상태 - 오류 발생으로 중단됨 */
+    ERROR = "error"
+}
+/**
+ * Actor 상태 인터페이스
+ * @description 액터의 현재 상태 정보
+ */
+export interface ActorStatus {
+    /** Actor ID */
+    id: ActorId;
+    /** Actor 이름 */
+    name: string;
+    /** Actor 역할 */
+    role: ActorRole;
+    /** 생명주기 상태 */
+    status: ActorLifecycleStatus;
+    /** 메시지 큐 상태 */
+    messageQueue: {
+        pending: number;
+        processing: boolean;
+    };
+    /** 현재 작업 */
+    currentTask?: {
+        id: TaskId;
+        type: string;
+        startedAt: Date;
+    };
+    /** 성능 메트릭 */
+    metrics: {
+        totalMessagesProcessed: number;
+        totalActionsExecuted: number;
+        totalErrors: number;
+        averageResponseTime: number;
+        uptime: number;
+    };
+    /** 마지막 활동 시간 */
+    lastSeen: Date;
+    /** 마지막 활동 유형 */
+    lastActivity?: "message_received" | "action_executed" | "error_occurred";
+    /** 에러 카운트 */
+    errorCount: number;
+    /** 마지막 에러 */
+    lastError?: {
+        message: string;
+        timestamp: Date;
+    };
+}
+/**
+ * 상태 전이 유효성 검사 함수
+ *
+ * 상태 전이 다이어그램:
+ * CREATED → STARTING
+ * STARTING → RUNNING | ERROR
+ * RUNNING → IDLE | BUSY | STOPPING | ERROR | RESTARTING
+ * IDLE → BUSY | STOPPING | RESTARTING
+ * BUSY → IDLE | ERROR | RESTARTING
+ * ERROR → RESTARTING | STOPPING
+ * RESTARTING → RUNNING | ERROR
+ * STOPPING → STOPPED
+ * STOPPED → (터미널 상태)
+ *
+ * @param current - 현재 상태
+ * @param next - 다음 상태
+ * @returns 전환 가능 여부
+ */
+export declare function isValidTransition(current: ActorLifecycleStatus, next: ActorLifecycleStatus): boolean;
+/**
+ * Actor 인터페이스
+ * @description 모든 액터가 구현해야 하는 기본 인터페이스
+ */
+export interface Actor {
+    /** 고유 식별자 */
+    readonly id: ActorId;
+    /** 액터 이름 */
+    readonly name: string;
+    /** 액터 역할 */
+    readonly role: ActorRole;
+    /** 현재 상태 */
+    readonly status: ActorStatus;
+    /** 공유 데이터 저장소 (Blackboard) */
+    board: IBlackboard;
+    /** 메시지 버스 (message.ts의 IMessageBus 타입 사용) */
+    messageBus: IMessageBus;
+    /** 마지막 활동 시간 */
+    lastActivity: Date;
+    /** 생성 시간 */
+    createdAt: Date;
+    /** 성능 메트릭 */
+    metrics: ActorMetrics;
+    /**
+     * 메시지 수신
+     * @param message - 수신할 메시지
+     * @returns 메시지 처리 결과
+     */
+    receive(message: Message): void | Promise<void>;
+    /**
+     * 환경 관찰
+     * @returns 관찰 결과
+     */
+    observe(): Observation | Promise<Observation>;
+    /**
+     * 의사결정 (생각)
+     * @param observation - 관찰 결과
+     * @returns 결정된 행동
+     */
+    think(observation: Observation): Action | Promise<Action>;
+    /**
+     * 행동 수행
+     * @param action - 수행할 행동
+     * @returns 행동 결과
+     */
+    act(action: Action): Result | Promise<Result>;
+    /**
+     * 결과 보고
+     * @param result - 보고할 결과
+     */
+    report(result: Result): void | Promise<void>;
+    /**
+     * 액터 시작
+     */
+    start(): void | Promise<void>;
+    /**
+     * 액터 중지
+     */
+    stop(): void | Promise<void>;
+    /**
+     * 액터 재시작
+     */
+    restart(): void | Promise<void>;
+    /**
+     * 액터 현재 상태 조회
+     */
+    getStatus(): ActorStatus;
+    /**
+     * 액터가 살아있는지 확인
+     */
+    isAlive(): boolean;
+}
+/**
+ * Actor ID 생성 함수
+ * @param role - Actor 역할
+ * @returns 브랜드 타입이 적용된 ActorId
+ * @example
+ * ```typescript
+ * const actorId = createActorId('analyst');
+ * // 결과: "analyst-550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+export declare function createActorId(role: ActorRole): ActorId;
+/**
+ * Actor ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 ActorId 여부
+ * @example
+ * ```typescript
+ * const value = 'analyst-550e8400-e29b-41d4-a716-446655440000';
+ * if (isValidActorId(value)) {
+ *   // value는 유효한 ActorId
+ * }
+ * ```
+ */
+export declare function isValidActorId(value: unknown): value is ActorId;
+/**
+ * Task ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 TaskId
+ * @example
+ * ```typescript
+ * const taskId = createTaskId('task-001');
+ * // 타입: TaskId
+ * ```
+ */
+export declare function createTaskId(id: string): TaskId;
+/**
+ * Task ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 TaskId 여부
+ * @example
+ * ```typescript
+ * const value = 'task-001';
+ * if (isValidTaskId(value)) {
+ *   // value는 유효한 TaskId
+ * }
+ * ```
+ */
+export declare function isValidTaskId(value: unknown): value is TaskId;
+export type { IBlackboard } from "./blackboard";

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

@@ -0,0 +1,46 @@
+/**
+ * @module blackboard
+ * @description Blackboard 인터페이스 - Actor 연결용
+ */
+/**
+ * Actor와 상호작용하는 Blackboard 인터페이스 (스펙 기준: IBlackboard)
+ *
+ * Actor 시스템에서 필요한 Blackboard의 기능을 정의합니다.
+ * 전체 구현은 @obora-kit/blackboard 패키지에서 제공됩니다.
+ *
+ * 참고: [[spec/13-actor.md|13-actor.md]]
+ */
+export interface IBlackboard {
+    /**
+     * 현재 Blackboard 버전
+     */
+    readonly version: number;
+    /**
+     * Blackboard에서 데이터 읽기
+     * @param key - 읽을 키 또는 경로
+     * @returns 읽은 데이터
+     */
+    read(key: string): unknown | undefined;
+    /**
+     * Blackboard에 데이터 쓰기
+     * @param key - 쓸 키 또는 경로
+     * @param value - 쓸 데이터
+     */
+    write(key: string, value: unknown): void;
+    /**
+     * Blackboard에서 데이터 삭제
+     * @param key - 삭제할 키 또는 경로
+     */
+    delete(key: string): void;
+    /**
+     * 모든 키 조회
+     * @returns 모든 키 배열
+     */
+    keys(): string[];
+    /**
+     * 특정 패턴의 키 조회
+     * @param pattern - 검색할 패턴
+     * @returns 일치하는 키 배열
+     */
+    find(pattern: string): string[];
+}

package/dist/_legacy/actor/types/crypto.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unified Actor ID generation using cryptographically-secure UUIDs.
+ * @param role Actor role to prefix the ID with
+ * @returns ActorId-style string: `<role>-<uuid>`
+ */
+export declare function generateActorId(role: string): string;

package/dist/_legacy/actor/types/message.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @module message
+ * @description Message 타입 정의 - 액터 간 통신
+ */
+import type { ActorId } from "./actor";
+/**
+ * Message 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+export type MessageId = string & {
+    readonly __brand: "MessageId";
+};
+/**
+ * 메시지 우선순위 열거형
+ * @description 메시지 처리 우선순위를 정의
+ */
+export declare enum MessagePriority {
+    /** 낮음 */
+    LOW = 0,
+    /** 보통 */
+    NORMAL = 1,
+    /** 높음 */
+    HIGH = 2,
+    /** 매우 높음 */
+    CRITICAL = 3
+}
+/**
+ * 메시지 유형 열거형
+ * @description 메시지의 종류를 정의
+ */
+export declare enum MessageType {
+    /** 상태 읽기 */
+    STATE_READ = "state.read",
+    /** 상태 쓰기 */
+    STATE_WRITE = "state.write",
+    /** 상태 구독 */
+    STATE_SUBSCRIBE = "state.subscribe",
+    /** 상태 구독 취소 */
+    STATE_UNSUBSCRIBE = "state.unsubscribe",
+    /** 작업 할당 */
+    TASK_ASSIGN = "task.assign",
+    /** 작업 시작 */
+    TASK_START = "task.start",
+    /** 작업 완료 */
+    TASK_COMPLETE = "task.complete",
+    /** 작업 실패 */
+    TASK_FAILED = "task.failed",
+    /** 작업 취소 */
+    TASK_CANCEL = "task.cancel",
+    /** 의사결정 요청 */
+    DECISION_REQUEST = "decision.request",
+    /** 의견 제출 */
+    OPINION_SUBMIT = "opinion.submit",
+    /** 의견 요청 */
+    OPINION_REQUEST = "opinion.request",
+    /** 투표 제출 */
+    VOTE_SUBMIT = "vote.submit",
+    /** 투표 요청 */
+    VOTE_REQUEST = "vote.request",
+    /** 합의 도달 */
+    CONSENSUS_REACHED = "consensus.reached",
+    /** 핑 */
+    PING = "ping",
+    /** 퐁 */
+    PONG = "pong",
+    /** 하트비트 */
+    HEARTBEAT = "heartbeat",
+    /** 상태 요청 */
+    STATUS_REQUEST = "status.request",
+    /** 상태 응답 */
+    STATUS_RESPONSE = "status.response",
+    /** 에러 */
+    ERROR = "error",
+    /** 에러 승인 */
+    ERROR_ACK = "error.ack",
+    /** 시작 */
+    START = "start",
+    /** 중지 */
+    STOP = "stop",
+    /** 재시작 */
+    RESTART = "restart",
+    /** 강제 종료 */
+    KILL = "kill",
+    /** 사용자 정의 메시지 */
+    CUSTOM = "custom"
+}
+/**
+ * Message 인터페이스
+ * @description 액터 간 통신에 사용되는 메시지
+ */
+export interface Message<T = unknown> {
+    /** 고유 식별자 */
+    id: MessageId;
+    /** 메시지 유형 */
+    type: MessageType;
+    /** 발신자 액터 ID */
+    from: ActorId;
+    /** 수신자 액터 ID ('broadcast' 시 전체 전송) */
+    to: ActorId | "broadcast";
+    /** 메시지 내용 */
+    payload: T;
+    /** 메시지 생성 시간 */
+    timestamp: Date;
+    /** 상관 관계 ID (선택적) - 응답 메시지와 요청 메시지 연결 */
+    correlationId?: string;
+    /** 응답 대상 (선택적) - 응답 메시지의 수신자 */
+    replyTo?: ActorId;
+    /** 메시지 우선순위 (선택적) */
+    priority?: MessagePriority;
+    /** Time to Live (선택적) - 메시지 유효 시간 (ms) */
+    ttl?: number;
+    /** 전달 확인 요청 (선택적) */
+    deliveryReceipt?: boolean;
+}
+/**
+ * 구독 취소 함수 타입
+ * @description 메시지 구독을 취소하는 함수
+ */
+export type UnsubscribeFn = () => void;
+/**
+ * IMessageBus 인터페이스
+ * @description 액터 간 메시지 전달 시스템
+ */
+export interface IMessageBus {
+    /**
+     * 메시지 전송
+     * @param message - 전송할 메시지
+     */
+    send(message: Message): void;
+    /**
+     * 특정 Actor에 메시지 전송
+     * @param to - 수신자 Actor ID
+     * @param message - 전송할 메시지 (to 필드 제외)
+     */
+    sendTo(to: ActorId, message: Omit<Message, "to">): void;
+    /**
+     * 브로드캐스트 전송
+     * @param message - 전송할 메시지 (to 필드 제외)
+     */
+    broadcast(message: Omit<Message, "to">): void;
+    /**
+     * 메시지 수신 핸들러 등록
+     * @param handler - 메시지 처리 핸들러
+     */
+    receive(handler: (message: Message) => void): void;
+    /**
+     * 요청-응답 패턴
+     * @param message - 요청 메시지
+     * @param timeoutMs - 타임아웃 시간 (ms)
+     * @returns 응답 메시지 Promise
+     */
+    request<T>(message: Message, timeoutMs?: number): Promise<Message<T>>;
+    /**
+     * 메시지 타입 구독
+     * @param messageType - 구독할 메시지 타입
+     * @param handler - 메시지 처리 핸들러
+     * @returns 구독 취소 함수
+     */
+    subscribe(messageType: MessageType, handler: (message: Message) => void): UnsubscribeFn;
+    /**
+     * 메시지 큐 크기 조회
+     * @param actorId - Actor ID
+     * @returns 큐에 대기 중인 메시지 수
+     */
+    getQueueSize(actorId: ActorId): number;
+    /**
+     * 메시지 큐 비우기
+     * @param actorId - Actor ID
+     */
+    clearQueue(actorId: ActorId): void;
+    /**
+     * 메시지 필터링
+     * @param predicate - 필터링 조건
+     */
+    filter(predicate: (message: Message) => boolean): Message[];
+}
+/**
+ * Message ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 MessageId
+ * @example
+ * ```typescript
+ * const messageId = createMessageId('msg-001');
+ * // 타입: MessageId
+ * ```
+ */
+export declare function createMessageId(id: string): MessageId;
+/**
+ * Message ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 MessageId 여부
+ */
+export declare function isValidMessageId(value: unknown): value is MessageId;
+/**
+ * Message 생성 함수
+ * @param params - Message 생성 파라미터
+ * @returns 생성된 Message 객체
+ * @example
+ * ```typescript
+ * const message = createMessage({
+ *   id: createMessageId('msg-001'),
+ *   type: MessageType.COMMAND,
+ *   from: createActorId('analyst-550e8400-e29b-41d4-a716-446655440000'),
+ *   to: createActorId('executor-550e8400-e29b-41d4-a716-446655440001'),
+ *   payload: { action: 'start' }
+ * });
+ * ```
+ */
+export declare function createMessage<T>(params: Omit<Message<T>, "timestamp">): Message<T>;

package/dist/_legacy/actor/types/metrics.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @module metrics
+ * @description Metrics 타입 정의 - 액터 성능 메트릭
+ */
+/**
+ * Actor 성능 메트릭 인터페이스
+ * @description 액터의 성능 및 실행 통계
+ */
+export interface ActorMetrics {
+    /** 총 실행 횟수 */
+    totalRuns: number;
+    /** 성공 횟수 */
+    successCount: number;
+    /** 실패 횟수 */
+    failureCount: number;
+    /** 마지막 오류 */
+    lastError: Error | null;
+    /** 평균 실행 시간 */
+    averageExecutionTime: number;
+    /** 총 실행 시간 (밀리초) */
+    totalExecutionTimeMs: number;
+    /** 마지막 실행 시간 */
+    lastRunAt?: Date;
+    /** 생성 시간 */
+    createdAt: Date;
+    /** 마지막 업데이트 시간 */
+    updatedAt: Date;
+    /** 마지막 실행 시간 (밀리초) */
+    lastExecutionTime: number | null;
+    /** 총 CPU 사용 시간 (밀리초) */
+    totalCpuTime: number;
+    /** 메모리 사용량 (바이트) */
+    memoryUsage: number;
+}
+/**
+ * Actor 메트릭 생성 함수
+ * @returns 생성된 ActorMetrics 객체
+ * @example
+ * ```typescript
+ * const metrics = createActorMetrics();
+ * ```
+ */
+export declare function createActorMetrics(): ActorMetrics;

package/dist/_legacy/actor/types/observation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module observation
+ * @description Observation 타입 정의 - 액터의 환경 관찰 결과
+ */
+import type { ActorId } from "./actor";
+/**
+ * 관찰 인터페이스
+ * @description 액터가 환경에서 관찰한 정보
+ */
+export interface Observation {
+    /** 관찰을 수행한 액터 ID */
+    actorId: ActorId;
+    /** 관찰 시간 */
+    timestamp: Date;
+    /** 관찰된 상태 (선택적) */
+    state?: {
+        context: Record<string, unknown>;
+        agents: unknown[];
+        tasks: unknown[];
+    };
+    /** 획득한 지식 (선택적) */
+    knowledge?: {
+        facts: unknown[];
+        inferences: unknown[];
+    };
+    /** 관찰된 결정사항 (선택적) */
+    decisions?: {
+        currentAgenda: unknown | null;
+        opinions: unknown[];
+    };
+}
+/**
+ * 관찰 생성 함수
+ * @param params - 관찰 생성 파라미터
+ * @returns 생성된 Observation 객체
+ * @example
+ * ```typescript
+ * const observation = createObservation({
+ *   actorId: createActorId('actor-001'),
+ *   state: { temperature: 25 },
+ *   knowledge: [{ id: 'k1', content: 'fact', confidence: 0.9 }]
+ * });
+ * ```
+ */
+export declare function createObservation(params: Omit<Observation, "timestamp">): Observation;