@obora/runtime 0.1.0

package/dist/_legacy/actor/runtime/ActorRuntime.d.ts

@@ -0,0 +1,161 @@
+import { ActorLifecycleStatus } from "../types/actor";
+import type { Actor, ActorId, ActorRole } from "../types/actor";
+import type { IBlackboard } from "../types/actor";
+import type { IMessageBus } from "../types/message";
+import type { ActorFactory, ActorConfig } from "./types";
+export declare class ActorStopTimeoutError extends Error {
+    constructor(actorId: ActorId);
+}
+/**
+ * Actor runtime configuration.
+ */
+export interface RuntimeConfig {
+    /** Maximum number of concurrent actors. */
+    maxActors?: number;
+    /** Default timeout for actor spawn/start in milliseconds. */
+    spawnTimeout?: number;
+    /** Default timeout for actor stop in milliseconds. */
+    stopTimeout?: number;
+    /** Maximum number of restart attempts. */
+    maxRestarts?: number;
+    /** Initial restart backoff in milliseconds. */
+    initialBackoff?: number;
+    /** Maximum restart backoff in milliseconds. */
+    maxBackoff?: number;
+    /** Enables debug logging. */
+    debug?: boolean;
+}
+/**
+ * Actor runtime.
+ *
+ * Responsible for actor creation, management, and shutdown.
+ */
+export interface RuntimeStopResult {
+    stopped: ActorId[];
+    failed: Array<{
+        id: ActorId;
+        error: unknown;
+    }>;
+}
+export declare class ActorRuntime {
+    private readonly actors;
+    private readonly actorConfigs;
+    private readonly spawningActorIds;
+    private readonly zombies;
+    private readonly board;
+    private readonly messageBus;
+    private readonly config;
+    private readonly factory;
+    private isRunning;
+    constructor(board: IBlackboard, messageBus: IMessageBus, factory: ActorFactory, config?: RuntimeConfig);
+    /**
+     * Starts the runtime.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the runtime.
+     */
+    stop(): Promise<RuntimeStopResult>;
+    /**
+     * Stops a specific actor by ID.
+     * @param actorId Actor ID.
+     */
+    stopById(actorId: ActorId): Promise<void>;
+    /**
+     * Spawns a new actor.
+     * @param config Actor configuration.
+     * @returns The created actor.
+     */
+    spawn(config: ActorConfig): Promise<Actor>;
+    /**
+     * Restarts an actor.
+     *
+     * Total restart attempts are capped at `maxRestarts`.
+     * @param actorId Actor ID.
+     * @param restartCount Current restart attempt count (internal use).
+     * @internal
+     */
+    restart(actorId: ActorId, restartCount?: number): Promise<Actor>;
+    /**
+     * Retries actor spawn with exponential backoff.
+     * @param actorId Actor ID.
+     * @param config Actor configuration.
+     * @param restartCount Current restart attempt count.
+     */
+    private retryRestart;
+    /**
+     * Gets an actor by ID.
+     * @param actorId Actor ID.
+     * @returns Actor instance.
+     */
+    getActor(actorId: ActorId): Actor;
+    /**
+     * Checks whether an actor exists.
+     * @param actorId Actor ID.
+     * @returns True if the actor exists.
+     */
+    hasActor(actorId: ActorId): boolean;
+    /**
+     * Returns all actor IDs.
+     * @returns Array of actor IDs.
+     */
+    listActors(): ActorId[];
+    /**
+     * Returns actors filtered by role.
+     * @param role Actor role.
+     * @returns Array of actor IDs.
+     */
+    listActorsByRole(role: ActorRole): ActorId[];
+    /**
+     * Returns actors filtered by lifecycle status.
+     * @param status Actor lifecycle status.
+     * @returns Array of actor IDs.
+     */
+    listActorsByStatus(status: ActorLifecycleStatus): ActorId[];
+    /**
+     * Returns the current number of actors.
+     */
+    size(): number;
+    /**
+     * Returns runtime status.
+     */
+    getStatus(): {
+        running: boolean;
+        actorCount: number;
+    };
+    /**
+     * Returns actor IDs that timed out during stop and may still be running.
+     */
+    getZombies(): ActorId[];
+    /**
+     * Stops a managed actor and releases runtime references.
+     *
+     * Timeout trade-off:
+     * - `actor.stop()` is raced against `stopTimeout`.
+     * - In `finally`, the runtime always removes actor/config map entries, even when
+     *   stop fails or times out.
+     *
+     * Why: keeping stale map entries blocks respawn/restart paths and leaks management state.
+     * Trade-off: the underlying actor implementation might still be running after timeout
+     * ("zombie" actor) because JavaScript promises are not force-cancelled.
+     */
+    private stopActor;
+    private isStopTimeoutError;
+    /**
+     * Calculates exponential backoff for restart attempts.
+     * @param restartCount Current restart attempt count.
+     * @returns Backoff duration in milliseconds.
+     */
+    private calculateBackoff;
+    /**
+     * Validates ActorConfig input.
+     * @param config ActorConfig to validate.
+     */
+    private validateConfig;
+    /**
+     * Validates RuntimeConfig input.
+     * @param config RuntimeConfig to validate.
+     */
+    private validateRuntimeConfig;
+    private log;
+}

package/dist/_legacy/actor/runtime/DefaultActorFactory.d.ts

@@ -0,0 +1,44 @@
+import type { Actor, ActorId, ActorRole, IBlackboard } from "../types/actor";
+import type { IMessageBus } from "../types/message";
+import type { ActorFactory, ActorConfig } from "./types";
+/**
+ * Actor 클래스 등록소
+ */
+type ActorConstructor = new (id: ActorId, name: string, role: ActorRole, board: IBlackboard, messageBus: IMessageBus, config?: Record<string, unknown>) => Actor;
+/**
+ * 기본 Actor 팩토리
+ *
+ * Actor 클래스를 등록하고 생성할 수 있는 팩토리입니다.
+ */
+export declare class DefaultActorFactory implements ActorFactory {
+    private readonly registry;
+    constructor();
+    /**
+     * Actor 클래스 등록
+     * @param type Actor 유형 식별자
+     * @param constructor Actor 생성자
+     */
+    register(type: string, constructor: ActorConstructor): void;
+    /**
+     * Actor 클래스 등록 해제
+     * @param type Actor 유형 식별자
+     */
+    unregister(type: string): void;
+    /**
+     * Actor 인스턴스 생성
+     * @param config Actor 설정
+     * @param board Blackboard 인스턴스
+     * @param messageBus MessageBus 인스턴스
+     * @returns 생성된 Actor 인스턴스
+     */
+    create(config: ActorConfig, board: IBlackboard, messageBus: IMessageBus, _options?: {
+        signal?: AbortSignal;
+    }): Promise<Actor>;
+    /**
+     * Actor ID 생성
+     * @param role Actor 역할
+     * @returns Actor ID
+     */
+    private generateId;
+}
+export {};

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

@@ -0,0 +1,41 @@
+import type { Actor, ActorId, ActorRole } from "../types/actor";
+import type { IBlackboard } from "../types/actor";
+import type { IMessageBus } from "../types/message";
+/**
+ * Actor 생성 설정
+ */
+export interface ActorConfig {
+    /** Actor ID (생략 시 자동 생성) */
+    id?: ActorId;
+    /** Actor 이름 */
+    name: string;
+    /** Actor 역할 */
+    role: ActorRole;
+    /** Actor 유형 (구체적인 Actor 클래스 식별자) */
+    type: string;
+    /** Actor 초기 설정 */
+    config?: Record<string, unknown>;
+}
+/**
+ * Actor 팩토리
+ *
+ * Actor 인스턴스 생성을 담당하는 인터페이스입니다.
+ * 구체적인 Actor 구현은 이 팩토리를 통해 생성됩니다.
+ */
+export interface ActorFactory {
+    /**
+     * Actor 인스턴스 생성
+     *
+     * Factory implementations SHOULD abort actor creation when `options.signal`
+     * is aborted.
+     *
+     * @param config Actor 설정
+     * @param board Blackboard 인스턴스
+     * @param messageBus MessageBus 인스턴스
+     * @param options 생성 옵션
+     * @returns 생성된 Actor 인스턴스
+     */
+    create(config: ActorConfig, board: IBlackboard, messageBus: IMessageBus, options?: {
+        signal?: AbortSignal;
+    }): Promise<Actor>;
+}

package/dist/_legacy/actor/runtime/utils/delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 지정된 시간만큼 대기하는 Promise를 반환합니다.
+ * @param ms 대기할 시간(밀리초)
+ * @param signal 취소 신호 (optional)
+ * @returns Promise<void>
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/_legacy/actor/supervision/Supervisor.d.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from "events";
+import type { ActorRuntime } from "../runtime/ActorRuntime";
+import type { ActorId } from "../types/actor";
+import { SupervisorConfig, RestartHistory, DeadLetter } from "./types";
+/**
+ * Supervisor
+ *
+ * Actor의 실패를 감지하고 재시작 전략에 따라 복구합니다.
+ */
+export declare class Supervisor extends EventEmitter {
+    private readonly config;
+    private readonly runtime;
+    private readonly restartCounts;
+    private readonly restartTimestamps;
+    private readonly restartHistory;
+    private readonly deadLetterQueue;
+    private readonly watchedActors;
+    private isRunning;
+    constructor(runtime: ActorRuntime, config?: Partial<SupervisorConfig>);
+    /**
+     * Supervisor 시작
+     */
+    start(): void;
+    /**
+     * Supervisor 종료
+     */
+    stop(): void;
+    /**
+     * Actor 감시 시작
+     * @param actorId 감시할 Actor ID
+     */
+    watch(actorId: ActorId): void;
+    /**
+     * Actor 감시 종료
+     * @param actorId 감시 종료할 Actor ID
+     */
+    unwatch(actorId: ActorId): void;
+    /**
+     * Actor 실패 처리
+     * @param actorId 실패한 Actor ID
+     * @param error 실패 원인
+     */
+    handleFailure(actorId: ActorId, error: Error): Promise<void>;
+    /**
+     * Dead Letter Queue 조회
+     */
+    getDeadLetters(): DeadLetter[];
+    /**
+     * Dead Letter Queue 비우기
+     */
+    clearDeadLetters(): void;
+    /**
+     * 재시작 이력 조회
+     */
+    getRestartHistory(actorId?: ActorId): RestartHistory[];
+    /**
+     * 감시 중인 Actor 목록
+     */
+    getWatchedActors(): ActorId[];
+    /**
+     * 재시작 결정
+     */
+    private decideRestart;
+    /**
+     * 재시작 수행
+     */
+    private performRestart;
+    /**
+     * OneForOne: 해당 Actor만 재시작
+     */
+    private restartOne;
+    /**
+     * AllForOne: 모든 감시 중인 Actor 재시작
+     */
+    private restartAll;
+    /**
+     * RestForOne: 해당 Actor와 이후 생성된 Actor들 재시작
+     */
+    private restartRest;
+    /**
+     * 정지 수행
+     */
+    private performStop;
+    /**
+     * 에스컬레이션
+     */
+    private escalate;
+    /**
+     * 백오프 계산
+     */
+    private calculateBackoff;
+    /**
+     * 이력 기록
+     */
+    private recordHistory;
+    /**
+     * Dead Letter 추가
+     */
+    private addDeadLetter;
+    private delay;
+    private log;
+}

package/dist/_legacy/actor/supervision/SupervisorTree.d.ts

@@ -0,0 +1,54 @@
+import type { ActorRuntime } from "../runtime/ActorRuntime";
+import { Supervisor } from "./Supervisor";
+import type { SupervisorConfig } from "./types";
+/**
+ * Supervisor Tree
+ *
+ * 계층적인 Supervisor 구조를 관리합니다.
+ * 상위 Supervisor가 하위 Supervisor와 Actor들을 감독합니다.
+ */
+export declare class SupervisorTree {
+    private readonly nodes;
+    private readonly runtime;
+    private rootId;
+    constructor(runtime: ActorRuntime);
+    /**
+     * 루트 Supervisor 생성
+     * @param config Supervisor 설정
+     * @returns 루트 Supervisor ID
+     */
+    createRoot(config?: Partial<SupervisorConfig>): string;
+    /**
+     * 자식 Supervisor 생성
+     * @param parentId 부모 Supervisor ID
+     * @param config Supervisor 설정
+     * @returns 자식 Supervisor ID
+     */
+    createChild(parentId: string, config?: Partial<SupervisorConfig>): string;
+    /**
+     * Supervisor 조회
+     * @param id Supervisor ID
+     * @returns Supervisor 인스턴스
+     */
+    getSupervisor(id: string): Supervisor;
+    /**
+     * 루트 Supervisor 조회
+     */
+    getRoot(): Supervisor | null;
+    /**
+     * Supervisor 제거
+     * @param id Supervisor ID
+     */
+    remove(id: string): void;
+    /**
+     * 전체 트리 정지
+     */
+    shutdown(): void;
+    /**
+     * 트리 구조 출력 (디버그용)
+     */
+    printTree(): string;
+    private handleEscalation;
+    private printNode;
+    private generateId;
+}

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

@@ -0,0 +1,130 @@
+import type { ActorId, Actor } from "../types/actor";
+/**
+ * 재시작 전략 유형
+ */
+export declare enum RestartStrategy {
+    /**
+     * OneForOne: 실패한 Actor만 재시작
+     * - 다른 Actor에 영향 없음
+     * - 독립적인 Actor에 적합
+     */
+    ONE_FOR_ONE = "one-for-one",
+    /**
+     * AllForOne: 하나가 실패하면 모든 Actor 재시작
+     * - 강한 의존성이 있는 Actor 그룹에 적합
+     * - 일관된 상태 복원 필요 시 사용
+     */
+    ALL_FOR_ONE = "all-for-one",
+    /**
+     * RestForOne: 실패한 Actor와 이후 생성된 Actor들 재시작
+     * - 순서 의존성이 있는 Actor에 적합
+     */
+    REST_FOR_ONE = "rest-for-one"
+}
+/**
+ * 재시작 지시
+ */
+export declare enum RestartDirective {
+    /** 재시작 */
+    RESTART = "restart",
+    /** 재시작하지 않음 (정상 종료 처리) */
+    STOP = "stop",
+    /** 상위 Supervisor로 에스컬레이션 */
+    ESCALATE = "escalate"
+}
+/**
+ * 백오프 정책 유형
+ */
+export declare enum BackoffPolicy {
+    /** 고정 대기 시간 */
+    FIXED = "fixed",
+    /** 지수 백오프 */
+    EXPONENTIAL = "exponential",
+    /** 선형 백오프 */
+    LINEAR = "linear",
+    /** 지터가 포함된 지수 백오프 */
+    EXPONENTIAL_JITTER = "exponential-jitter"
+}
+/**
+ * 백오프 설정
+ */
+export interface BackoffConfig {
+    /** 백오프 정책 */
+    policy: BackoffPolicy;
+    /** 초기 대기 시간 (ms) */
+    initialDelay: number;
+    /** 최대 대기 시간 (ms) */
+    maxDelay: number;
+    /** 지수/선형 배율 */
+    multiplier?: number;
+    /** 지터 범위 (0-1) */
+    jitterFactor?: number;
+}
+/**
+ * Supervisor 설정
+ */
+export interface SupervisorConfig {
+    /** 재시작 전략 */
+    strategy: RestartStrategy;
+    /** 백오프 설정 */
+    backoff: BackoffConfig;
+    /** 최대 재시작 횟수 (기간 내) */
+    maxRestarts: number;
+    /** 재시작 횟수 리셋 기간 (ms) */
+    restartWindow: number;
+    /** 재시작 결정 함수 (커스텀 로직) */
+    decider?: (error: Error, actor: Actor) => RestartDirective;
+    /** Dead Letter Queue 활성화 */
+    enableDeadLetterQueue?: boolean;
+    /** Dead Letter Queue 최대 크기 */
+    deadLetterQueueSize?: number;
+    /** 디버그 모드 */
+    debug?: boolean;
+}
+/**
+ * 재시작 이력
+ */
+export interface RestartHistory {
+    /** Actor ID */
+    actorId: ActorId;
+    /** 재시작 시간 */
+    timestamp: Date;
+    /** 재시작 원인 에러 */
+    error: Error;
+    /** 재시작 시도 횟수 */
+    attempt: number;
+    /** 재시작 성공 여부 */
+    success: boolean;
+}
+/**
+ * Dead Letter
+ */
+export interface DeadLetter {
+    /** 원본 메시지/작업 */
+    payload: unknown;
+    /** 실패한 Actor ID */
+    actorId: ActorId;
+    /** 실패 에러 */
+    error: Error;
+    /** 실패 시간 */
+    timestamp: Date;
+    /** 재시도 횟수 */
+    retryCount: number;
+}
+/**
+ * Supervisor 이벤트
+ */
+export interface SupervisorEvents {
+    /** Actor 실패 시 */
+    "actor:failed": (actorId: ActorId, error: Error) => void;
+    /** Actor 재시작 시 */
+    "actor:restarted": (actorId: ActorId, attempt: number) => void;
+    /** Actor 영구 정지 시 */
+    "actor:stopped": (actorId: ActorId, reason: string) => void;
+    /** Dead Letter 발생 시 */
+    "dead-letter": (letter: DeadLetter) => void;
+    /** 최대 재시작 초과 시 */
+    "max-restarts-exceeded": (actorId: ActorId) => void;
+    /** 에스컬레이션 */
+    escalate: (actorId: ActorId, error: Error) => void;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * @module action
+ * @description Action 타입 정의 - 액터가 수행하는 행동
+ */
+import type { ActorId } from "./actor";
+/**
+ * Action 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+export type ActionId = string & {
+    readonly __brand: "ActionId";
+};
+/**
+ * Action 유형
+ * @description 액터가 수행할 수 있는 행동의 종류
+ */
+export type ActionType = "analyze" | "execute" | "verify" | "coordinate" | "submit_opinion" | "submit_vote" | "create_agenda" | "unknown";
+/**
+ * Action 인터페이스
+ * @description 액터가 수행하는 행동의 정의
+ */
+export interface Action {
+    /** 고유 식별자 */
+    readonly id: ActionId;
+    /** 행동을 수행하는 액터 ID */
+    actorId: ActorId;
+    /** 행동 유형 */
+    type: ActionType;
+    /** 행동 생성 시간 */
+    timestamp: Date;
+    /** 행동 파라미터 (선택적) */
+    params?: Record<string, unknown>;
+    /** 관련 작업 ID (선택적) */
+    taskId?: string;
+}
+/**
+ * Action ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 ActionId
+ * @example
+ * ```typescript
+ * const actionId = createActionId('action-001');
+ * // 타입: ActionId
+ * ```
+ */
+export declare function createActionId(id: string): ActionId;
+/**
+ * Action ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 ActionId 여부
+ */
+export declare function isValidActionId(value: unknown): value is ActionId;
+/**
+ * Action 생성 함수
+ * @param actorId - 액터 ID
+ * @param type - 행동 유형
+ * @param params - 행동 파라미터 (선택적)
+ * @param taskId - 관련 작업 ID (선택적)
+ * @returns 생성된 Action 객체
+ * @example
+ * ```typescript
+ * const action = createAction('actor-001', 'analyze', { target: 'data-001' });
+ * ```
+ */
+export declare function createAction(actorId: ActorId, type: ActionType, params?: Record<string, unknown>, taskId?: string): Action;