@obora/runtime 0.1.0

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

@@ -0,0 +1,189 @@
+/**
+ * @module types/tkg
+ * @description Temporal Knowledge Graph(TKG) 타입/계약 (spec/12 정렬)
+ */
+import type { AgentId } from './base';
+/** TKG 노드 ID */
+export type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+/** TKG 엣지 ID */
+export type EdgeId = string & {
+    readonly __brand: 'EdgeId';
+};
+/** 노드 ID 생성기 */
+export declare function createNodeId(id: string): NodeId;
+/** 엣지 ID 생성기 */
+export declare function createEdgeId(id: string): EdgeId;
+/** 노드 종류 */
+export type TemporalNodeType = 'entity' | 'fact' | 'decision' | 'task' | 'pattern';
+/** 엣지 종류 */
+export type EdgeType = 'relates_to' | 'part_of' | 'contains' | 'supports' | 'contradicts' | 'explains' | 'based_on' | 'decided_by' | 'decided_on' | 'leads_to' | 'assigned_to' | 'depends_on' | 'blocks' | 'precedes' | 'exemplifies' | 'generalizes' | 'specializes';
+export interface EntityData {
+    readonly name: string;
+    readonly entityType: 'agent' | 'task' | 'resource' | 'concept';
+    readonly attributes: Readonly<Record<string, unknown>>;
+}
+export interface FactData {
+    readonly statement: string;
+    readonly context?: string;
+    readonly evidence?: readonly NodeId[];
+    readonly verified: boolean;
+}
+export interface DecisionData {
+    readonly agendaId: string;
+    readonly outcome: 'approve' | 'reject' | 'deferred';
+    readonly reason: string;
+    readonly participants: readonly AgentId[];
+}
+export interface TaskData {
+    readonly description: string;
+    readonly status: 'pending' | 'running' | 'completed' | 'failed';
+    readonly assignedTo?: AgentId;
+    readonly result?: unknown;
+}
+export interface PatternData {
+    readonly description: string;
+    readonly frequency: number;
+    readonly examples: readonly string[];
+    readonly accuracy?: number;
+}
+export type NodeData = EntityData | FactData | DecisionData | TaskData | PatternData;
+/**
+ * 시간축을 가진 TKG 노드
+ */
+export interface TemporalNode {
+    readonly id: NodeId;
+    readonly type: TemporalNodeType;
+    readonly valid_from: Date;
+    readonly valid_to?: Date;
+    readonly observed_at: Date;
+    readonly updated_at: Date;
+    readonly confidence: number;
+    readonly source: AgentId;
+    readonly version: number;
+    readonly tags?: readonly string[];
+    readonly data: NodeData;
+}
+/**
+ * 시간축을 가진 TKG 엣지
+ */
+export interface TemporalEdge {
+    readonly id: EdgeId;
+    readonly from: NodeId;
+    readonly to: NodeId;
+    readonly type: EdgeType;
+    readonly valid_from: Date;
+    readonly valid_to?: Date;
+    readonly observed_at: Date;
+    readonly confidence: number;
+    readonly source: AgentId;
+    readonly weight?: number;
+}
+/**
+ * TKG 조회 쿼리
+ */
+export interface GraphQuery {
+    readonly nodeTypes?: readonly TemporalNodeType[];
+    readonly nodeIds?: readonly NodeId[];
+    readonly tags?: readonly string[];
+    readonly minConfidence?: number;
+    readonly edgeTypes?: readonly EdgeType[];
+    readonly from?: NodeId;
+    readonly to?: NodeId;
+    readonly depth?: number;
+}
+/**
+ * TKG 조회 결과
+ */
+export interface QueryResult {
+    readonly nodes: readonly TemporalNode[];
+    readonly edges: readonly TemporalEdge[];
+    readonly metadata: {
+        readonly queryTime: Date;
+        readonly resultCount: number;
+        readonly confidenceRange: readonly [number, number];
+    };
+}
+export interface ValidationError {
+    readonly field: string;
+    readonly message: string;
+    readonly code: string;
+}
+export interface ValidationWarning {
+    readonly field: string;
+    readonly message: string;
+    readonly code: string;
+}
+/**
+ * 유효성 검사 결과
+ */
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+    readonly warnings: readonly ValidationWarning[];
+}
+export type ConflictResolution = 'pending' | 'supersedes' | 'higher_confidence' | 'merge' | 'discard' | 'soft_delete';
+export interface Conflict {
+    readonly id: string;
+    readonly type: 'version' | 'contradiction' | 'supersedes' | 'confidence';
+    readonly nodes: readonly [TemporalNode, TemporalNode];
+    readonly detectedAt: Date;
+    readonly status: 'pending' | 'resolved' | 'deferred';
+    readonly resolution?: ConflictResolution;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 승격(Promotion) 메타데이터
+ */
+export interface PromotionMeta {
+    readonly promotedBy?: string;
+    readonly reason?: string;
+    readonly promotedAt?: Date;
+}
+/**
+ * 개별 승격 결과
+ */
+export interface PromotionResult {
+    readonly nodeId: NodeId;
+    readonly success: boolean;
+    readonly timestamp: Date;
+    readonly reason?: string;
+    readonly conflict?: Conflict;
+}
+/**
+ * 병합 옵션
+ */
+export interface ReflectionOptions {
+    readonly minConfidence?: number;
+    readonly resolveConflicts?: boolean;
+    readonly softDeleteOnConflict?: boolean;
+    readonly maxAge?: number;
+}
+/**
+ * Staging/Production 병합 결과
+ */
+export interface MergeResult {
+    readonly mergeId: string;
+    readonly timestamp: Date;
+    readonly nodesPromoted: number;
+    readonly nodesSkipped: number;
+    readonly nodesFailed: number;
+    readonly edgesPromoted: number;
+    readonly edgesSkipped: number;
+    readonly conflicts: readonly Conflict[];
+    readonly duration: number;
+}
+/**
+ * Production 승격 전용 Port 계약.
+ * Reflector는 ProductionTKG 내부 맵에 직접 쓰지 않고 반드시 이 포트를 사용해야 합니다.
+ */
+export interface IProductionPromotionPort {
+    promoteNode(node: TemporalNode, meta?: PromotionMeta): PromotionResult;
+    promoteEdge(edge: TemporalEdge, meta?: PromotionMeta): PromotionResult;
+    promoteBatch(payload: {
+        nodes: readonly TemporalNode[];
+        edges: readonly TemporalEdge[];
+        meta?: PromotionMeta;
+    }): MergeResult;
+}

package/dist/cell/ActorPool.d.ts

@@ -0,0 +1 @@
+export * from "../_legacy/actor/pool/ActorPool.js";

package/dist/cell/AgentFactory.d.ts

@@ -0,0 +1 @@
+export * from "../_legacy/agents/roles/factory.js";

package/dist/cell/AgentRegistry.d.ts

@@ -0,0 +1 @@
+export * from "../_legacy/cli-runtime/runtime/agent-registry.js";

package/dist/cell/BaseActor.d.ts

@@ -0,0 +1 @@
+export { BaseActor } from "../_legacy/actor/base/BaseActor.js";

package/dist/cell/CellContext.d.ts

@@ -0,0 +1,39 @@
+import type { CellConfig, CellId, Task } from "./types.js";
+export interface StateAccessor {
+    read(path: string): unknown;
+    write(path: string, value: unknown): void;
+}
+export interface ToolSet {
+    invoke(toolName: string, params: unknown): Promise<unknown>;
+}
+export interface AuditRecorder {
+    record(eventType: string, data: Record<string, unknown>): Promise<void> | void;
+}
+export interface ToolCallPreHookInput {
+    cellId: CellId;
+    toolName: string;
+    params: unknown;
+    task: Task;
+}
+export interface ToolCallPostHookInput extends ToolCallPreHookInput {
+    durationMs: number;
+    result?: unknown;
+    error?: Error;
+}
+export interface CellPolicyHooks {
+    beforeExecute?(task: Task): Promise<void> | void;
+    afterExecute?(task: Task, outcome: {
+        success: boolean;
+        output: unknown;
+    }): Promise<void> | void;
+    beforeToolCall?(input: ToolCallPreHookInput): Promise<void> | void;
+    afterToolCall?(input: ToolCallPostHookInput): Promise<void> | void;
+}
+export interface CellContext {
+    cellId: CellId;
+    blackboard: StateAccessor;
+    tools: ToolSet;
+    audit: AuditRecorder;
+    policy?: CellPolicyHooks;
+    config: CellConfig;
+}

package/dist/cell/CellManager.d.ts

@@ -0,0 +1,80 @@
+import { ActorRuntime, ActorStopTimeoutError } from "../_legacy/actor/runtime/ActorRuntime.js";
+import type { CellContext } from "./CellContext.js";
+import type { CellConfig, CellId, CellResult, CellStatus, Task } from "./types.js";
+export type CellDispatchStrategy = "fifo" | "priority";
+export interface CellRegistrationOptions {
+    id?: CellId;
+    config?: CellConfig;
+    context?: CellContext;
+    runTask?: (task: Task, context: CellContext) => Promise<unknown>;
+}
+export interface CellManagerTaskOptions {
+    priority?: number;
+}
+export interface CellManagerConfig {
+    maxConcurrentExecutions?: number;
+    maxQueuedExecutions?: number;
+    dispatchStrategy?: CellDispatchStrategy;
+    defaultCellConfig?: CellConfig;
+    createCellContext: (cellId: CellId, config: CellConfig) => CellContext;
+    createCell?: (options: {
+        id: CellId;
+        context: CellContext;
+        config: CellConfig;
+        runTask?: (task: Task, context: CellContext) => Promise<unknown>;
+    }) => {
+        readonly id: CellId;
+        readonly status: CellStatus;
+        execute(task: Task): Promise<CellResult>;
+        suspend(): Promise<void>;
+        resume(): Promise<void>;
+        abort(reason: string): Promise<void>;
+    };
+}
+export interface CellSnapshot {
+    id: CellId;
+    status: CellStatus;
+    config: CellConfig;
+}
+export declare class CellManager {
+    private readonly config;
+    private readonly cells;
+    private readonly queue;
+    private readonly inFlight;
+    private readonly maxConcurrentExecutions;
+    private readonly maxQueuedExecutions;
+    private readonly dispatchStrategy;
+    private readonly defaultCellConfig;
+    constructor(config: CellManagerConfig);
+    createCell(options?: CellRegistrationOptions): CellId;
+    getCell(id: CellId): {
+        readonly id: CellId;
+        readonly status: CellStatus;
+        execute(task: Task): Promise<CellResult>;
+        suspend(): Promise<void>;
+        resume(): Promise<void>;
+        abort(reason: string): Promise<void>;
+    } | undefined;
+    getCellSnapshot(id: CellId): CellSnapshot | undefined;
+    listCells(): CellSnapshot[];
+    execute(cellId: CellId, task: Task, options?: CellManagerTaskOptions): Promise<CellResult>;
+    suspendCell(id: CellId): Promise<void>;
+    resumeCell(id: CellId): Promise<void>;
+    stopCell(id: CellId, reason?: string): Promise<void>;
+    stopAll(reason?: string): Promise<void>;
+    getQueueSize(): number;
+    getRunningCount(): number;
+    getStatus(): {
+        totalCells: number;
+        running: number;
+        queued: number;
+    };
+    private processQueue;
+    private pickNext;
+    private runQueueItem;
+    private requireCell;
+    private rejectQueuedTasksForCell;
+    private validateConfig;
+}
+export { ActorRuntime, ActorStopTimeoutError };
+export * from "../_legacy/actor/runtime/ActorRuntime.js";

package/dist/cell/ExecutionCell.d.ts

@@ -0,0 +1,44 @@
+import type { ActorRole } from "../_legacy/actor/types/actor.js";
+import type { CellId, CellResult, CellStatus, Task } from "./types.js";
+import type { CellContext } from "./CellContext.js";
+export interface ExecutionCell {
+    readonly id: CellId;
+    readonly status: CellStatus;
+    execute(task: Task): Promise<CellResult>;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    abort(reason: string): Promise<void>;
+}
+interface DefaultExecutionCellOptions {
+    id: CellId;
+    context: CellContext;
+    runTask?: (task: Task, context: CellContext) => Promise<unknown>;
+    actorRole?: ActorRole;
+    actorName?: string;
+}
+export declare class DefaultExecutionCell implements ExecutionCell {
+    readonly id: CellId;
+    private readonly actor;
+    private readonly rawContext;
+    private readonly defaultRunner;
+    private readonly stateChanges;
+    private readonly toolCalls;
+    private statusValue;
+    private abortReason;
+    private suspendedResolver;
+    private suspendedWaiter;
+    constructor(options: DefaultExecutionCellOptions);
+    get status(): CellStatus;
+    execute(task: Task): Promise<CellResult>;
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    abort(reason: string): Promise<void>;
+    private buildInstrumentedContext;
+    private wrapBlackboard;
+    private wrapTools;
+    private withTimeout;
+    private waitIfSuspended;
+    private throwIfAborted;
+    private recordAudit;
+}
+export {};

package/dist/cell/PoolManager.d.ts

@@ -0,0 +1 @@
+export * from "../_legacy/actor/pool/PoolManager.js";

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

package/dist/cell/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";