depa-actor 0.1.2 → 0.2.0

package/src/execution/dispatcher.ts

@@ -0,0 +1,188 @@
+import type { InstructionStack, OperandStack } from './stack.js';
+
+export interface KernelInstruction<TOpcode extends string = string, TMemo = unknown> {
+  opcode: TOpcode;
+  memo?: TMemo;
+  comment?: string;
+}
+
+export interface DispatchContext<TRuntime, TInstruction extends KernelInstruction, TValue> {
+  runtime: TRuntime;
+  instructionStack: InstructionStack<TInstruction>;
+  operandStack: OperandStack<TValue>;
+}
+
+export type InstructionHandler<
+  TRuntime,
+  TInstruction extends KernelInstruction,
+  TValue,
+  TEffect = unknown,
+> = (args: {
+  runtime: TRuntime;
+  instruction: TInstruction;
+  instructionStack: InstructionStack<TInstruction>;
+  operandStack: OperandStack<TValue>;
+}) => void | DispatchHandlerResult<TEffect>;
+
+export interface DispatchHandlerResult<TEffect = unknown> {
+  effects?: TEffect[];
+  stop?: boolean;
+  stopReason?: string;
+  yield?: boolean;
+  yieldReason?: string;
+}
+
+export type InstructionHandlerResolver<
+  TRuntime,
+  TInstruction extends KernelInstruction,
+  TValue,
+  TEffect = unknown,
+> = (opcode: TInstruction['opcode']) =>
+  | InstructionHandler<TRuntime, TInstruction, TValue, TEffect>
+  | undefined;
+
+export interface DispatchOptions {
+  maxInstructions?: number;
+  shouldStop?: (args: { executed: number }) => string | false | undefined;
+  hooks?: DispatchLifecycleHooks<KernelInstruction, unknown>;
+}
+
+export interface InstructionExecLog<TInstruction extends KernelInstruction> {
+  instruction: TInstruction;
+  result: 'ok' | 'stop' | 'yield' | 'missing_handler' | 'error';
+  error?: string;
+}
+
+export type DispatchStopReason =
+  | 'instruction_stack_empty'
+  | 'budget_exhausted'
+  | 'handler_requested_stop'
+  | 'yield_requested'
+  | 'missing_handler'
+  | 'error'
+  | 'custom';
+
+export type DispatchInstructionResult = InstructionExecLog<KernelInstruction>['result'];
+
+export interface DispatchLifecycleHooks<
+  TInstruction extends KernelInstruction = KernelInstruction,
+  TEffect = unknown,
+> {
+  beforeInstruction?: (args: { instruction: TInstruction; executed: number }) => void;
+  afterInstruction?: (args: {
+    instruction: TInstruction;
+    executed: number;
+    result: DispatchInstructionResult;
+  }) => void;
+  onHandlerEffects?: (args: { instruction: TInstruction; effects: TEffect[]; executed: number }) => void;
+  onStop?: (args: {
+    stopReason: DispatchStopReason;
+    stopDetail?: string;
+    executed: number;
+  }) => void;
+}
+
+export interface DispatchResult<TInstruction extends KernelInstruction, TEffect = unknown> {
+  executed: number;
+  stopReason: DispatchStopReason;
+  stopDetail?: string;
+  effects: TEffect[];
+  trace: InstructionExecLog<TInstruction>[];
+  error?: unknown;
+}
+
+export function dispatchInstructions<
+  TRuntime,
+  TInstruction extends KernelInstruction,
+  TValue,
+  TEffect = unknown,
+>(
+  context: DispatchContext<TRuntime, TInstruction, TValue>,
+  resolveHandler: InstructionHandlerResolver<TRuntime, TInstruction, TValue, TEffect>,
+  options?: DispatchOptions & { hooks?: DispatchLifecycleHooks<TInstruction, TEffect> },
+): DispatchResult<TInstruction, TEffect> {
+  const maxInstructions = options?.maxInstructions ?? Number.POSITIVE_INFINITY;
+  const effects: TEffect[] = [];
+  const trace: InstructionExecLog<TInstruction>[] = [];
+  let executed = 0;
+
+  const finish = (
+    stopReason: DispatchStopReason,
+    stopDetail?: string,
+    error?: unknown,
+  ): DispatchResult<TInstruction, TEffect> => {
+    options?.hooks?.onStop?.({ stopReason, stopDetail, executed });
+    const result: DispatchResult<TInstruction, TEffect> = { executed, stopReason, effects, trace };
+    if (stopDetail !== undefined) {
+      result.stopDetail = stopDetail;
+    }
+    if (error !== undefined) {
+      result.error = error;
+    }
+    return result;
+  };
+
+  while (executed < maxInstructions) {
+    const customStop = options?.shouldStop?.({ executed });
+    if (customStop) {
+      return finish('custom', customStop);
+    }
+
+    const instruction = context.instructionStack.pop();
+    if (!instruction) {
+      return finish('instruction_stack_empty');
+    }
+
+    options?.hooks?.beforeInstruction?.({ instruction, executed });
+
+    const handler = resolveHandler(instruction.opcode);
+    if (!handler) {
+      trace.push({ instruction, result: 'missing_handler' });
+      options?.hooks?.afterInstruction?.({ instruction, executed, result: 'missing_handler' });
+      return finish('missing_handler');
+    }
+
+    try {
+      const handlerResult = handler({
+        runtime: context.runtime,
+        instruction,
+        instructionStack: context.instructionStack,
+        operandStack: context.operandStack,
+      });
+      executed += 1;
+      if (handlerResult?.effects) {
+        effects.push(...handlerResult.effects);
+        options?.hooks?.onHandlerEffects?.({
+          instruction,
+          effects: handlerResult.effects,
+          executed,
+        });
+      }
+      if (handlerResult?.yield) {
+        trace.push({ instruction, result: 'yield' });
+        const stopDetail = handlerResult.yieldReason;
+        options?.hooks?.afterInstruction?.({ instruction, executed, result: 'yield' });
+        return finish('yield_requested', stopDetail);
+      }
+      if (handlerResult?.stop) {
+        trace.push({ instruction, result: 'stop' });
+        const stopDetail = handlerResult.stopReason;
+        const stopReason = stopDetail === undefined ? 'handler_requested_stop' : 'custom';
+        options?.hooks?.afterInstruction?.({ instruction, executed, result: 'stop' });
+        return finish(stopReason, stopDetail);
+      }
+      trace.push({ instruction, result: 'ok' });
+      options?.hooks?.afterInstruction?.({ instruction, executed, result: 'ok' });
+    } catch (error) {
+      trace.push({
+        instruction,
+        result: 'error',
+        error: error instanceof Error ? error.message : String(error),
+      });
+      options?.hooks?.afterInstruction?.({ instruction, executed, result: 'error' });
+      return finish('error', undefined, error);
+    }
+  }
+
+  return finish('budget_exhausted');
+}

package/src/execution/index.ts

@@ -0,0 +1,58 @@
+export type {
+  StackMachine,
+  StackMachineState,
+  InstructionStack,
+  OperandStack,
+} from './stack.js';
+export {
+  createStackMachine,
+  createInstructionStack,
+  createOperandStack,
+} from './stack.js';
+
+export type {
+  CommandDeque,
+  CommandDequeDefinition,
+  CommandDequeGroup,
+  CommandDequeGroupMutationResult,
+  CommandDequeGroupOptions,
+  CommandDequeGroupState,
+  CommandDequeId,
+  CommandDequeItem,
+  CommandDequeOptions,
+  CommandDequeSelection,
+  CommandDequeSelector,
+  CommandDequeState,
+  CommandDequeMutationResult,
+  PushCommandOptions,
+  PushCommandToDequeOptions,
+  SelectedCommandDequeItem,
+} from './commandDeque.js';
+export {
+  createCommandDeque,
+  createCommandDequeGroup,
+  defaultCommandDequeSelector,
+  drainCommandDequeFromGroup,
+  drainWhereCommandDequeFromGroup,
+  popBackCommand,
+  popFrontCommand,
+  popNextCommand,
+  popSelectedCommandFromGroup,
+  pushBackCommand,
+  pushBackCommandToGroup,
+  pushFrontCommand,
+  pushFrontCommandToGroup,
+  takeNextCommandFromGroup,
+} from './commandDeque.js';
+
+export type {
+  DispatchContext,
+  DispatchHandlerResult,
+  DispatchOptions,
+  DispatchResult,
+  InstructionExecLog,
+  InstructionHandler,
+  InstructionHandlerResolver,
+  KernelInstruction,
+} from './dispatcher.js';
+export { dispatchInstructions } from './dispatcher.js';

package/src/execution/stack.ts

@@ -0,0 +1,130 @@
+export interface StackMachineState<TItem> {
+  items: TItem[];
+  frameBottoms: number[];
+}
+
+export interface StackMachine<TItem> {
+  readonly size: number;
+  readonly frameDepth: number;
+  push(value: TItem): void;
+  pushItems(values: Iterable<TItem>): void;
+  pop(): TItem | undefined;
+  peek(): TItem | undefined;
+  pushFrame(): void;
+  popFrameAllValues(): TItem[];
+  popFrameAndPushTopValue(): TItem | undefined;
+  peekBottomOfAllFrames(): TItem | undefined;
+  snapshot(): StackMachineState<TItem>;
+  loadSnapshot(state: StackMachineState<TItem>): void;
+}
+
+class ArrayStackMachine<TItem> implements StackMachine<TItem> {
+  private readonly items: TItem[];
+  private readonly frameBottoms: number[];
+
+  constructor(state?: StackMachineState<TItem>) {
+    this.items = [...(state?.items ?? [])];
+    this.frameBottoms = [...(state?.frameBottoms ?? [])];
+    this.validateFrameBottoms();
+  }
+
+  get size(): number {
+    return this.items.length;
+  }
+
+  get frameDepth(): number {
+    return this.frameBottoms.length;
+  }
+
+  push(value: TItem): void {
+    this.items.push(value);
+  }
+
+  pushItems(values: Iterable<TItem>): void {
+    for (const value of values) {
+      this.push(value);
+    }
+  }
+
+  pop(): TItem | undefined {
+    return this.items.pop();
+  }
+
+  peek(): TItem | undefined {
+    return this.items.at(-1);
+  }
+
+  pushFrame(): void {
+    this.frameBottoms.push(this.items.length);
+  }
+
+  popFrameAllValues(): TItem[] {
+    const frameBottom = this.popFrameBottom();
+    return this.items.splice(frameBottom);
+  }
+
+  popFrameAndPushTopValue(): TItem | undefined {
+    const values = this.popFrameAllValues();
+    const topValue = values.at(-1);
+    if (topValue !== undefined) {
+      this.items.push(topValue);
+    }
+    return topValue;
+  }
+
+  peekBottomOfAllFrames(): TItem | undefined {
+    return this.items[0];
+  }
+
+  snapshot(): StackMachineState<TItem> {
+    return {
+      items: [...this.items],
+      frameBottoms: [...this.frameBottoms],
+    };
+  }
+
+  loadSnapshot(state: StackMachineState<TItem>): void {
+    this.items.splice(0, this.items.length, ...(state.items ?? []));
+    this.frameBottoms.splice(0, this.frameBottoms.length, ...(state.frameBottoms ?? []));
+    this.validateFrameBottoms();
+  }
+
+  private popFrameBottom(): number {
+    const frameBottom = this.frameBottoms.pop();
+    if (frameBottom === undefined) {
+      throw new Error('Cannot pop frame: no frame is open');
+    }
+    return frameBottom;
+  }
+
+  private validateFrameBottoms(): void {
+    let previous = 0;
+    for (const frameBottom of this.frameBottoms) {
+      if (!Number.isInteger(frameBottom) || frameBottom < previous || frameBottom > this.items.length) {
+        throw new Error(`Invalid frame bottom index: ${frameBottom}`);
+      }
+      previous = frameBottom;
+    }
+  }
+}
+
+export type InstructionStack<TInstruction> = StackMachine<TInstruction>;
+export type OperandStack<TValue> = StackMachine<TValue>;
+
+export function createStackMachine<TItem>(
+  state?: StackMachineState<TItem>,
+): StackMachine<TItem> {
+  return new ArrayStackMachine(state);
+}
+
+export function createInstructionStack<TInstruction>(
+  state?: StackMachineState<TInstruction>,
+): InstructionStack<TInstruction> {
+  return createStackMachine(state);
+}
+
+export function createOperandStack<TValue>(
+  state?: StackMachineState<TValue>,
+): OperandStack<TValue> {
+  return createStackMachine(state);
+}

package/src/index.ts

@@ -11,22 +11,22 @@ export type {
   ActorDef,
   ActorLogKind,
   ActorLogEntry,
-} from './core/types';
+} from './core/types.js';
 
-export { ActorSystem } from './core/ActorSystem';
+export { ActorSystem } from './core/ActorSystem.js';
 
 // depa-actor — Runtime
-export type { ActorPlugin } from './runtime/ActorRuntime';
-export { ActorRuntime } from './runtime/ActorRuntime';
+export type { ActorPlugin } from './runtime/ActorRuntime.js';
+export { ActorRuntime } from './runtime/ActorRuntime.js';
 export {
   CompletionSignalRegistry,
   CompletionBindingRegistry,
   createCompletionSignalRegistry,
   createCompletionBindingRegistry,
-} from './runtime/completion';
+} from './runtime/completion.js';
 export type {
   CompletionWaiter,
-} from './runtime/completion';
+} from './runtime/completion.js';
 export type {
   SnapshotRecoveryState,
   RuntimeSnapshotManifestBase,
@@ -36,13 +36,65 @@ export type {
   SnapshotCodec,
   RecoveryHooks,
   PersistenceEffectPort,
-} from './runtime/snapshot';
+} from './runtime/snapshot.js';
 export {
   createSnapshotCodec,
   createRecoveryHooks,
   createPersistenceEffectPort,
-} from './runtime/snapshot';
-export { RuntimeIndexHook, createRuntimeIndexHook } from './runtime/indexing';
+} from './runtime/snapshot.js';
+export { RuntimeIndexHook, createRuntimeIndexHook } from './runtime/indexing.js';
+
+// depa-actor — Execution kernel primitives
+export type {
+  StackMachine,
+  StackMachineState,
+  InstructionStack,
+  OperandStack,
+  CommandDeque,
+  CommandDequeDefinition,
+  CommandDequeGroup,
+  CommandDequeGroupMutationResult,
+  CommandDequeGroupOptions,
+  CommandDequeGroupState,
+  CommandDequeId,
+  CommandDequeItem,
+  CommandDequeOptions,
+  CommandDequeSelection,
+  CommandDequeSelector,
+  CommandDequeState,
+  CommandDequeMutationResult,
+  PushCommandOptions,
+  PushCommandToDequeOptions,
+  SelectedCommandDequeItem,
+  DispatchContext,
+  DispatchHandlerResult,
+  DispatchOptions,
+  DispatchResult,
+  InstructionExecLog,
+  InstructionHandler,
+  InstructionHandlerResolver,
+  KernelInstruction,
+} from './execution/index.js';
+export {
+  createStackMachine,
+  createInstructionStack,
+  createOperandStack,
+  createCommandDeque,
+  createCommandDequeGroup,
+  defaultCommandDequeSelector,
+  drainCommandDequeFromGroup,
+  drainWhereCommandDequeFromGroup,
+  popBackCommand,
+  popFrontCommand,
+  popNextCommand,
+  popSelectedCommandFromGroup,
+  pushBackCommand,
+  pushBackCommandToGroup,
+  pushFrontCommand,
+  pushFrontCommandToGroup,
+  takeNextCommandFromGroup,
+  dispatchInstructions,
+} from './execution/index.js';
 
 // depa-actor — Pipeline (DOP bridge)
 export type {
@@ -53,12 +105,12 @@ export type {
   PipelineInnerConfigAdapter,
   PipelineCoreLogic,
   PipelineOutputAdapter,
-} from './pipeline/ActorPipeline';
-export { createPipelineHandler } from './pipeline/ActorPipeline';
+} from './pipeline/ActorPipeline.js';
+export { createPipelineHandler } from './pipeline/ActorPipeline.js';
 
 // depa-actor — Dispatch bridge
-export type { DispatchRoute } from './dispatch/ActorDispatchAdapter';
-export { createDispatchHandler } from './dispatch/ActorDispatchAdapter';
+export type { DispatchRoute } from './dispatch/ActorDispatchAdapter.js';
+export { createDispatchHandler } from './dispatch/ActorDispatchAdapter.js';
 
 // depa-actor — Orchestration (Fiber Scheduling)
 export type {
@@ -77,7 +129,7 @@ export type {
   FiberEffect,
   ReduceResult,
   ScheduleResult,
-} from './orchestration';
+} from './orchestration/index.js';
 
 export {
   DEFAULT_ORCHESTRATOR_OPTIONS,
@@ -89,4 +141,4 @@ export {
   scheduleOne,
   createAiAgentSchedulerHooks,
   dispatchEffects,
-} from './orchestration';
+} from './orchestration/index.js';

package/src/orchestration/index.ts

@@ -15,21 +15,21 @@ export type {
   FiberAction,
   FiberEffect,
   ReduceResult,
-} from './types';
+} from './types.js';
 
-export { DEFAULT_ORCHESTRATOR_OPTIONS } from './types';
+export { DEFAULT_ORCHESTRATOR_OPTIONS } from './types.js';
 
-export { createOrchestratorState, reduceOrchestrator } from './reducer';
+export { createOrchestratorState, reduceOrchestrator } from './reducer.js';
 
-export { applyFailure } from './recovery';
+export { applyFailure } from './recovery.js';
 
 export {
   computeEffectivePriority,
   selectNextFiberId,
   scheduleOne,
-} from './scheduler';
-export type { ScheduleResult } from './scheduler';
+} from './scheduler.js';
+export type { ScheduleResult } from './scheduler.js';
 
-export { createAiAgentSchedulerHooks } from './presets/aiAgent';
+export { createAiAgentSchedulerHooks } from './presets/aiAgent.js';
 
-export { dispatchEffects } from './runtimeAdapter';
+export { dispatchEffects } from './runtimeAdapter.js';

package/src/orchestration/presets/aiAgent.ts

@@ -1,6 +1,6 @@
-import type { MailboxSchema } from '../../core/types';
+import type { MailboxSchema } from '../../core/types.js';
 
-import type { FiberRecord, OrchestratorState, SchedulerHooks, SuspendPolicy } from '../types';
+import type { FiberRecord, OrchestratorState, SchedulerHooks, SuspendPolicy } from '../types.js';
 
 function isAiHumanWaitReason(reason: unknown): boolean {
   return reason === 'human_clarification' || reason === 'human_approval' || reason === 'human_answer';

package/src/orchestration/recovery.ts

@@ -1,5 +1,5 @@
-import type { MailboxSchema } from '../core/types';
-import type { FiberEffect, FiberId, FiberRecord, OrchestratorState, ReduceResult } from './types';
+import type { MailboxSchema } from '../core/types.js';
+import type { FiberEffect, FiberId, FiberRecord, OrchestratorState, ReduceResult } from './types.js';
 
 function cloneFiberMap<TSchema extends MailboxSchema>(
   state: OrchestratorState<TSchema>,

package/src/orchestration/reducer.ts

@@ -1,5 +1,5 @@
-import type { MailboxSchema } from '../core/types';
-import { applyFailure } from './recovery';
+import type { MailboxSchema } from '../core/types.js';
+import { applyFailure } from './recovery.js';
 import {
   DEFAULT_ORCHESTRATOR_OPTIONS,
   type FiberAction,
@@ -10,7 +10,7 @@ import {
   type ReduceResult,
   type SpawnFiberInput,
   type SuspendPolicy,
-} from './types';
+} from './types.js';
 
 function isTerminalStatus(status: FiberRecord<MailboxSchema>['status']): boolean {
   return status === 'completed' || status === 'cancelled' || status === 'failed' || status === 'dead_letter';

package/src/orchestration/runtimeAdapter.ts

@@ -1,6 +1,6 @@
-import type { MailboxSchema } from '../core/types';
-import type { ActorRuntime } from '../runtime/ActorRuntime';
-import type { FiberEffect } from './types';
+import type { MailboxSchema } from '../core/types.js';
+import type { ActorRuntime } from '../runtime/ActorRuntime.js';
+import type { FiberEffect } from './types.js';
 
 export function dispatchEffects<TRuntime, TSchema extends MailboxSchema>(
   runtime: ActorRuntime<TRuntime, TSchema>,

package/src/orchestration/scheduler.ts

@@ -1,5 +1,5 @@
-import type { MailboxSchema } from '../core/types';
-import type { FiberEffect, FiberId, FiberRecord, OrchestratorState } from './types';
+import type { MailboxSchema } from '../core/types.js';
+import type { FiberEffect, FiberId, FiberRecord, OrchestratorState } from './types.js';
 
 export interface ScheduleResult<TSchema extends MailboxSchema> {
   state: OrchestratorState<TSchema>;

package/src/orchestration/types.ts

@@ -1,4 +1,4 @@
-import type { MailboxSchema } from '../core/types';
+import type { MailboxSchema } from '../core/types.js';
 
 export type FiberId = string;
 

package/src/pipeline/ActorPipeline.ts

@@ -15,7 +15,7 @@ import type {
   MailboxSchema,
   ActorSelf,
   ActorHandler,
-} from '../core/types';
+} from '../core/types.js';
 
 // ─── Pipeline Adapter Types ──────────────────────────────────────────
 

package/src/runtime/ActorRuntime.ts

@@ -12,8 +12,8 @@ import type {
   ActorDef,
   ActorRef,
   ActorLogEntry,
-} from '../core/types';
-import { ActorSystem } from '../core/ActorSystem';
+} from '../core/types.js';
+import { ActorSystem } from '../core/ActorSystem.js';
 
 // ─── Plugin ──────────────────────────────────────────────────────────