@obora/runtime 0.1.0

package/dist/cell/actor-types/blackboard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module blackboard
+ * @description Blackboard 인터페이스 - Actor 연결용
+ */
+/**
+ * Actor와 상호작용하는 Blackboard 인터페이스 (스펙 기준: IBlackboard)
+ *
+ * Actor 시스템에서 필요한 Blackboard의 기능을 정의합니다.
+ * 전체 구현은 runtime 내부 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/cell/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/cell/actor-types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module types
+ * @description Actor 패키지 타입 정의 모듈
+ */
+export * from "./actor";
+export * from "./blackboard";
+export * from "./observation";
+export * from "./action";
+export * from "./result";
+export * from "./message";
+export * from "./metrics";
+export * from "./crypto";

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

package/dist/cell/actor-types/result.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @module result
+ * @description Result 타입 정의 - Action 수행 결과
+ */
+import type { ActionId } from "./action";
+import type { ActorId } from "./actor";
+/**
+ * Result 고유 ID 타입
+ * @description 브랜드 타입을 사용하여 타입 안전성을 확보
+ */
+export type ResultId = string & {
+    readonly __brand: "ResultId";
+};
+/**
+ * Result 상태
+ * @description 행동 수행 결과의 상태
+ */
+export type ResultStatus = "success" | "failure" | "partial";
+/**
+ * Result 메트릭
+ * @description 행동 수행의 성능 메트릭
+ */
+export interface ResultMetrics {
+    /** 실행 시간 (밀리초) */
+    duration: number;
+    /** 메모리 사용량 (바이트) */
+    memoryUsage?: number;
+    /** 추가 메트릭 */
+    [key: string]: unknown;
+}
+/**
+ * Result 인터페이스
+ * @description Action 수행 결과
+ */
+export interface Result {
+    /** 고유 식별자 */
+    readonly id: ResultId;
+    /** 관련 Action ID */
+    actionId: ActionId;
+    /** 결과를 생성한 액터 ID */
+    actorId: ActorId;
+    /** 결과 생성 시간 */
+    timestamp: Date;
+    /** 결과 상태 */
+    status: ResultStatus;
+    /** 출력 데이터 (성공 시) */
+    output?: unknown;
+    /** 오류 정보 (실패 시) - 문자열 형태 */
+    error?: string;
+    /** 성능 메트릭 */
+    metrics?: ResultMetrics;
+    /** 보드에 기록할 데이터 */
+    toRecord?: {
+        section: "state" | "knowledge" | "decisions";
+        data: unknown;
+    };
+}
+/**
+ * Result ID 생성 함수
+ * @param id - 원본 문자열 ID
+ * @returns 브랜드 타입이 적용된 ResultId
+ * @example
+ * ```typescript
+ * const resultId = createResultId('result-001');
+ * // 타입: ResultId
+ * ```
+ */
+export declare function createResultId(id: string): ResultId;
+/**
+ * Result ID 유효성 검사
+ * @param value - 확인할 값
+ * @returns 유효한 ResultId 여부
+ */
+export declare function isValidResultId(value: unknown): value is ResultId;
+/**
+ * 성공 Result 생성 함수
+ * @param actionId - Action ID
+ * @param actorId - 액터 ID
+ * @param output - 출력 데이터
+ * @param duration - 실행 시간 (밀리초)
+ * @returns 생성된 성공 Result 객체
+ * @example
+ * ```typescript
+ * const result = createSuccessResult(
+ *   createActionId('action-001'),
+ *   createActorId('actor-001'),
+ *   { data: 'analysis result' },
+ *   100
+ * );
+ * ```
+ */
+export declare function createSuccessResult(actionId: ActionId, actorId: ActorId, output: unknown, duration: number): Result;
+/**
+ * 실패 Result 생성 함수
+ * @param actionId - Action ID
+ * @param actorId - 액터 ID
+ * @param error - 오류 메시지
+ * @param duration - 실행 시간 (밀리초)
+ * @returns 생성된 실패 Result 객체
+ * @example
+ * ```typescript
+ * const result = createFailureResult(
+ *   createActionId('action-001'),
+ *   createActorId('actor-001'),
+ *   'Analysis failed',
+ *   50
+ * );
+ * ```
+ */
+export declare function createFailureResult(actionId: ActionId, actorId: ActorId, error: string, duration: number): Result;

package/dist/cell/agents/AnalystCellAgent.d.ts

@@ -0,0 +1,2 @@
+export { AnalystAgent as AnalystCellAgent } from "../../_legacy/agents/roles/analyst-agent.js";
+export * from "../../_legacy/agents/roles/analyst-agent.js";

package/dist/cell/agents/BaseRuntimeAgent.d.ts

@@ -0,0 +1,2 @@
+export { BaseAgent as BaseRuntimeAgent } from "../../_legacy/agents/roles/base-agent.js";
+export * from "../../_legacy/agents/roles/base-agent.js";

package/dist/cell/agents/DirectorCellAgent.d.ts

@@ -0,0 +1,2 @@
+export { DirectorAgent as DirectorCellAgent } from "../../_legacy/agents/roles/director-agent.js";
+export * from "../../_legacy/agents/roles/director-agent.js";

package/dist/cell/agents/ExecutorCellAgent.d.ts

@@ -0,0 +1,2 @@
+export { ExecutorAgent as ExecutorCellAgent } from "../../_legacy/agents/roles/executor-agent.js";
+export * from "../../_legacy/agents/roles/executor-agent.js";

package/dist/cell/agents/VerifierCellAgent.d.ts

@@ -0,0 +1,2 @@
+export { VerifierAgent as VerifierCellAgent } from "../../_legacy/agents/roles/verifier-agent.js";
+export * from "../../_legacy/agents/roles/verifier-agent.js";

package/dist/cell/agents/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./BaseRuntimeAgent.js";
+export * from "./AnalystCellAgent.js";
+export * from "./ExecutorCellAgent.js";
+export * from "./VerifierCellAgent.js";
+export * from "./DirectorCellAgent.js";

package/dist/cell/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./BaseActor.js";
+export * from "./CellManager.js";
+export * from "./PoolManager.js";
+export * from "./ExecutionCell.js";
+export * from "./CellContext.js";
+export * from "./types.js";
+export * from "./internal/ActorRunnerAdapter.js";
+export * from "./internal/CellActorFactory.js";
+export * from "./internal/NoOpRuntimeBus.js";

package/dist/cell/internal/ActorRunnerAdapter.d.ts

@@ -0,0 +1,2 @@
+export { ActorRunner as ActorRunnerAdapter } from "../../_legacy/actor/runtime/ActorRunner.js";
+export * from "../../_legacy/actor/runtime/ActorRunner.js";

package/dist/cell/internal/CellActorFactory.d.ts

@@ -0,0 +1,2 @@
+export { DefaultActorFactory as CellActorFactory } from "../../_legacy/actor/runtime/DefaultActorFactory.js";
+export * from "../../_legacy/actor/runtime/DefaultActorFactory.js";

package/dist/cell/internal/NoOpRuntimeBus.d.ts

@@ -0,0 +1,2 @@
+export { NoOpMessageBus as NoOpRuntimeBus } from "../../_legacy/actor/pool/NoOpMessageBus.js";
+export * from "../../_legacy/actor/pool/NoOpMessageBus.js";

package/dist/cell/internal/delay.d.ts

@@ -0,0 +1 @@
+export * from "../../_legacy/actor/runtime/utils/delay.js";

package/dist/cell/pool-index.d.ts

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

package/dist/cell/types.d.ts

@@ -0,0 +1,47 @@
+export type CellId = string;
+export type CellStatus = "idle" | "running" | "completed" | "failed" | "suspended";
+export interface CellConfig {
+    timeout?: number;
+    maxToolCalls?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface StateChange {
+    path: string;
+    oldValue: unknown;
+    newValue: unknown;
+    timestamp: Date;
+}
+export interface ToolCallRecord {
+    id: string;
+    toolName: string;
+    params: unknown;
+    status: "success" | "error";
+    result?: unknown;
+    error?: string;
+    startedAt: Date;
+    endedAt: Date;
+    durationMs: number;
+}
+export interface CellMetrics {
+    startTime: Date;
+    endTime: Date;
+    durationMs: number;
+    tokenCount?: number;
+    toolCallCount: number;
+    costUsd?: number;
+}
+export interface CellResult {
+    success: boolean;
+    output: unknown;
+    stateChanges: StateChange[];
+    toolCalls: ToolCallRecord[];
+    metrics: CellMetrics;
+}
+export interface Task {
+    id: string;
+    type: string;
+    description: string;
+    input: unknown;
+    priority: number;
+    metadata?: Record<string, unknown>;
+}

package/dist/checkpoint/CheckpointFactoryRegistry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * M6-02: CheckpointableFactory registry
+ *
+ * Manages type→factory mappings for restoring checkpointed state.
+ */
+import type { CheckpointableFactory } from "../storage/types.js";
+export declare class CheckpointFactoryNotFoundError extends Error {
+    readonly typeName: string;
+    constructor(typeName: string);
+}
+export declare class CheckpointFactoryRegistry {
+    private readonly factories;
+    register<T>(typeName: string, factory: CheckpointableFactory<T>): void;
+    get<T>(typeName: string): CheckpointableFactory<T>;
+    has(typeName: string): boolean;
+}

package/dist/checkpoint/CheckpointManager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * M6-02: CheckpointManager — Creates and restores checkpoints for run resume.
+ *
+ * Responsibilities:
+ * - Save checkpoint after each step completion
+ * - Load latest checkpoint for a run
+ * - Detect policy drift
+ * - Determine step restoration policy
+ */
+import type { StorageAdapter, CheckpointRecord, StepRecord, ResumeOptions } from "../storage/types.js";
+import { type PolicyHashInput } from "./policy-hash.js";
+export interface CheckpointStepPolicy {
+    stepName: string;
+    action: "restore" | "rerun" | "skip";
+    output?: Record<string, unknown>;
+}
+export interface PolicyDriftResult {
+    drifted: boolean;
+    oldHash: string;
+    newHash: string;
+}
+export declare class PolicyDriftError extends Error {
+    readonly oldHash: string;
+    readonly newHash: string;
+    constructor(oldHash: string, newHash: string);
+}
+export declare class CheckpointManager {
+    private readonly storage;
+    constructor(storage: StorageAdapter);
+    saveCheckpoint(runId: string, stepName: string, completedSteps: string[], stateSnapshot: unknown, policyConfig: PolicyHashInput): Promise<CheckpointRecord>;
+    getLatestCheckpoint(runId: string): Promise<CheckpointRecord | null>;
+    detectDrift(checkpoint: CheckpointRecord, currentPolicyConfig: PolicyHashInput): PolicyDriftResult;
+    /**
+     * Determine step restoration policy per the design spec:
+     * - completed → restore (use cached output)
+     * - failed → rerun
+     * - running → rerun
+     * - skipped → skip
+     */
+    resolveStepPolicies(steps: StepRecord[], completedSteps: string[], allStepNames: string[], options?: ResumeOptions): CheckpointStepPolicy[];
+}

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,5 @@
+export { CheckpointManager, PolicyDriftError } from "./CheckpointManager.js";
+export type { CheckpointStepPolicy, PolicyDriftResult } from "./CheckpointManager.js";
+export { CheckpointFactoryRegistry, CheckpointFactoryNotFoundError } from "./CheckpointFactoryRegistry.js";
+export { computePolicyHash } from "./policy-hash.js";
+export type { PolicyHashInput } from "./policy-hash.js";

package/dist/checkpoint/policy-hash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * M6-02: Policy hash computation for drift detection.
+ *
+ * Includes resources + policies config; excludes persistence/artifacts settings.
+ * Uses deterministic JSON serialization (sorted keys) + SHA-256.
+ */
+export interface PolicyHashInput {
+    resources?: Record<string, unknown>;
+    policies?: Record<string, unknown>;
+}
+export declare function computePolicyHash(input: PolicyHashInput): string;