depa-actor 0.1.0

package/src/core/types.ts

@@ -0,0 +1,136 @@
+/**
+ * depa-actor — Core Type Definitions
+ *
+ * Synthesizes:
+ * - depa-data-graph ActorSystem (true actor model, mailbox queue, microtask drain)
+ * - depa-processor (dispatch routing, DOP pipeline)
+ * - OneAgentActor domain needs (multi-mailbox, typed tags)
+ */
+
+// ─── MailboxSchema ───────────────────────────────────────────────────
+// Record<tag, payload> — each key is a mailbox name, value is payload type.
+// Example: { cancel: boolean; human_input: string; tool_call: ToolCallData }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export type MailboxSchema = Record<string, unknown>;
+
+// ─── ActorEnvelope ───────────────────────────────────────────────────
+// tag + payload replaces the old single `msg` field.
+
+export interface ActorEnvelope<TSchema extends MailboxSchema = MailboxSchema> {
+  id: number;
+  ts: number;
+  from: string;
+  to: string;
+  tag: keyof TSchema & string;
+  payload: TSchema[keyof TSchema & string];
+}
+
+/** Type-safe envelope for a specific tag */
+export type TaggedEnvelope<
+  TSchema extends MailboxSchema,
+  TTag extends keyof TSchema & string,
+> = Omit<ActorEnvelope<TSchema>, 'tag' | 'payload'> & {
+  tag: TTag;
+  payload: TSchema[TTag];
+};
+
+// ─── Mailbox Priority ────────────────────────────────────────────────
+
+export type MailboxPriority<TSchema extends MailboxSchema> = {
+  [K in keyof TSchema & string]?: number;
+};
+
+// ─── ActorRef ────────────────────────────────────────────────────────
+// Capability-based reference: can send, no management.
+
+export interface ActorRef<TSchema extends MailboxSchema = MailboxSchema> {
+  readonly id: string;
+  send<TTag extends keyof TSchema & string>(tag: TTag, payload: TSchema[TTag]): void;
+}
+
+// ─── ActorSelf ───────────────────────────────────────────────────────
+// Handler-side reference with state access and selective receive.
+
+export interface ActorSelf<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState = void,
+> {
+  readonly id: string;
+  readonly ref: ActorRef<TSchema>;
+  readonly runtime: TRuntime;
+  state: TState;
+
+  /** Send to a specific actor */
+  send(to: string, tag: keyof TSchema & string, payload: TSchema[keyof TSchema & string]): void;
+
+  /** Broadcast to all actors */
+  broadcast(
+    tag: keyof TSchema & string,
+    payload: TSchema[keyof TSchema & string],
+    opts?: { excludeSelf?: boolean },
+  ): void;
+
+  // ── Selective Receive ──
+  /** Check if there are pending messages for a specific tag */
+  hasPending<TTag extends keyof TSchema & string>(tag: TTag): boolean;
+
+  /** Drain all pending messages for a specific tag (removes them from queue) */
+  drainMailbox<TTag extends keyof TSchema & string>(tag: TTag): TaggedEnvelope<TSchema, TTag>[];
+}
+
+// ─── ActorHandler ────────────────────────────────────────────────────
+
+/** Unified handler — receives all envelopes, switch on tag */
+export type ActorHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState = void,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: ActorEnvelope<TSchema>,
+) => void | Promise<void>;
+
+/** Per-tag handler — handles a single tag */
+export type TagHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+  TTag extends keyof TSchema & string,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: TaggedEnvelope<TSchema, TTag>,
+) => void | Promise<void>;
+
+// ─── ActorDef ────────────────────────────────────────────────────────
+// Definition for registering an actor. Supports both unified and per-tag handlers.
+
+export interface ActorDef<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState = void,
+> {
+  initialState: TState;
+
+  /** Mailbox priority — lower number = higher priority. Default: 100 */
+  priority?: MailboxPriority<TSchema>;
+
+  /** Unified handler (fallback for tags not in `handlers`) */
+  handler?: ActorHandler<TRuntime, TSchema, TState>;
+
+  /** Per-tag handlers — takes precedence over `handler` for matching tags */
+  handlers?: {
+    [TTag in keyof TSchema & string]?: TagHandler<TRuntime, TSchema, TState, TTag>;
+  };
+}
+
+// ─── Log ─────────────────────────────────────────────────────────────
+
+export type ActorLogKind = 'send' | 'deliver' | 'error';
+
+export interface ActorLogEntry<TSchema extends MailboxSchema = MailboxSchema>
+  extends ActorEnvelope<TSchema> {
+  kind: ActorLogKind;
+  error?: string;
+}

package/src/dispatch/ActorDispatchAdapter.ts

@@ -0,0 +1,84 @@
+/**
+ * depa-actor — Dispatch Bridge
+ *
+ * Optional bridge to depa-processor DispatchEngine.
+ * Only this file imports from depa-processor concepts.
+ * No hard dependency — uses structural typing.
+ */
+
+import type {
+  MailboxSchema,
+  ActorSelf,
+  ActorEnvelope,
+  ActorHandler,
+} from '../core/types';
+
+// ─── DispatchRoute (structural, no import) ───────────────────────────
+
+/**
+ * A dispatch route maps a tag to a dispatch key and handler.
+ * This is a structural interface — no dependency on depa-processor.
+ */
+export interface DispatchRoute<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+> {
+  /** Which tags this route handles */
+  tags: (keyof TSchema & string)[];
+
+  /** Resolve dispatch key from envelope */
+  resolveKey: (envelope: ActorEnvelope<TSchema>) => string;
+
+  /** Route table: dispatch key → handler */
+  routes: Record<string, (
+    self: ActorSelf<TRuntime, TSchema, TState>,
+    envelope: ActorEnvelope<TSchema>,
+  ) => void | Promise<void>>;
+
+  /** Fallback if no route matches */
+  fallback?: (
+    self: ActorSelf<TRuntime, TSchema, TState>,
+    envelope: ActorEnvelope<TSchema>,
+    key: string,
+  ) => void | Promise<void>;
+}
+
+// ─── createDispatchHandler ───────────────────────────────────────────
+
+/**
+ * Creates an ActorHandler that routes envelopes through dispatch routes.
+ * Falls back to `defaultHandler` for tags not covered by any route.
+ */
+export function createDispatchHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+>(
+  routes: DispatchRoute<TRuntime, TSchema, TState>[],
+  defaultHandler?: ActorHandler<TRuntime, TSchema, TState>,
+): ActorHandler<TRuntime, TSchema, TState> {
+  // Build tag → route index for O(1) lookup
+  const tagIndex = new Map<string, DispatchRoute<TRuntime, TSchema, TState>>();
+  for (const route of routes) {
+    for (const tag of route.tags) {
+      tagIndex.set(tag, route);
+    }
+  }
+
+  return async (self, envelope) => {
+    const route = tagIndex.get(envelope.tag);
+
+    if (route) {
+      const key = route.resolveKey(envelope);
+      const handler = route.routes[key];
+      if (handler) {
+        await handler(self, envelope);
+      } else if (route.fallback) {
+        await route.fallback(self, envelope, key);
+      }
+    } else if (defaultHandler) {
+      await defaultHandler(self, envelope);
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+// depa-actor — Core
+export type {
+  MailboxSchema,
+  ActorEnvelope,
+  TaggedEnvelope,
+  MailboxPriority,
+  ActorRef,
+  ActorSelf,
+  ActorHandler,
+  TagHandler,
+  ActorDef,
+  ActorLogKind,
+  ActorLogEntry,
+} from './core/types';
+
+export { ActorSystem } from './core/ActorSystem';
+
+// depa-actor — Runtime
+export type { ActorPlugin } from './runtime/ActorRuntime';
+export { ActorRuntime } from './runtime/ActorRuntime';
+export {
+  CompletionSignalRegistry,
+  CompletionBindingRegistry,
+  createCompletionSignalRegistry,
+  createCompletionBindingRegistry,
+} from './runtime/completion';
+export type {
+  CompletionWaiter,
+} from './runtime/completion';
+export type {
+  SnapshotRecoveryState,
+  RuntimeSnapshotManifestBase,
+  RuntimeRootSnapshotBase,
+  ActorSnapshotBase,
+  FiberSnapshotBase,
+  SnapshotCodec,
+  RecoveryHooks,
+  PersistenceEffectPort,
+} from './runtime/snapshot';
+export {
+  createSnapshotCodec,
+  createRecoveryHooks,
+  createPersistenceEffectPort,
+} from './runtime/snapshot';
+export { RuntimeIndexHook, createRuntimeIndexHook } from './runtime/indexing';
+
+// depa-actor — Pipeline (DOP bridge)
+export type {
+  ActorPipelineDef,
+  PipelineDerivedAdapter,
+  PipelineInnerRuntimeAdapter,
+  PipelineInnerInputAdapter,
+  PipelineInnerConfigAdapter,
+  PipelineCoreLogic,
+  PipelineOutputAdapter,
+} from './pipeline/ActorPipeline';
+export { createPipelineHandler } from './pipeline/ActorPipeline';
+
+// depa-actor — Dispatch bridge
+export type { DispatchRoute } from './dispatch/ActorDispatchAdapter';
+export { createDispatchHandler } from './dispatch/ActorDispatchAdapter';
+
+// depa-actor — Orchestration (Fiber Scheduling)
+export type {
+  FiberId,
+  FiberStatus,
+  FiberWaitingReason,
+  SuspendPolicy,
+  SchedulerHooks,
+  FiberStep,
+  FiberRecord,
+  SpawnFiberInput,
+  DeadLetterRecord,
+  OrchestratorOptions,
+  OrchestratorState,
+  FiberAction,
+  FiberEffect,
+  ReduceResult,
+  ScheduleResult,
+} from './orchestration';
+
+export {
+  DEFAULT_ORCHESTRATOR_OPTIONS,
+  createOrchestratorState,
+  reduceOrchestrator,
+  applyFailure,
+  computeEffectivePriority,
+  selectNextFiberId,
+  scheduleOne,
+  createAiAgentSchedulerHooks,
+  dispatchEffects,
+} from './orchestration';

package/src/orchestration/index.ts

@@ -0,0 +1,35 @@
+// depa-actor — Orchestration (Fiber Scheduling)
+
+export type {
+  FiberId,
+  FiberStatus,
+  FiberWaitingReason,
+  SuspendPolicy,
+  SchedulerHooks,
+  FiberStep,
+  FiberRecord,
+  SpawnFiberInput,
+  DeadLetterRecord,
+  OrchestratorOptions,
+  OrchestratorState,
+  FiberAction,
+  FiberEffect,
+  ReduceResult,
+} from './types';
+
+export { DEFAULT_ORCHESTRATOR_OPTIONS } from './types';
+
+export { createOrchestratorState, reduceOrchestrator } from './reducer';
+
+export { applyFailure } from './recovery';
+
+export {
+  computeEffectivePriority,
+  selectNextFiberId,
+  scheduleOne,
+} from './scheduler';
+export type { ScheduleResult } from './scheduler';
+
+export { createAiAgentSchedulerHooks } from './presets/aiAgent';
+
+export { dispatchEffects } from './runtimeAdapter';

package/src/orchestration/presets/aiAgent.ts

@@ -0,0 +1,48 @@
+import type { MailboxSchema } from '../../core/types';
+
+import type { FiberRecord, OrchestratorState, SchedulerHooks, SuspendPolicy } from '../types';
+
+function isAiHumanWaitReason(reason: unknown): boolean {
+  return reason === 'human_clarification' || reason === 'human_approval' || reason === 'human_answer';
+}
+
+function getEffectiveSuspendPolicy(fiber: FiberRecord<MailboxSchema>): SuspendPolicy | undefined {
+  const raw = (fiber as any)?.suspendPolicy;
+  return raw === 'continue_others' || raw === 'pause_all' ? raw : undefined;
+}
+
+function isBlockingLaneForPauseAll(lane: unknown): boolean {
+  // Treat any non-background lane as blocking by default.
+  if (lane === 'background' || lane === 'collective') {
+    return false;
+  }
+  return true;
+}
+
+function isAllowedLaneDuringPauseAll(lane: unknown): boolean {
+  return lane === 'background' || lane === 'collective';
+}
+
+function hasPauseAllHumanWaitInBlockingLane<TSchema extends MailboxSchema>(state: OrchestratorState<TSchema>): boolean {
+  return Object.values(state.fibers as any).some((fiber: any) => {
+    return (
+      fiber?.status === 'suspended' &&
+      isAiHumanWaitReason(fiber?.waitingReason) &&
+      getEffectiveSuspendPolicy(fiber as FiberRecord<MailboxSchema>) === 'pause_all' &&
+      isBlockingLaneForPauseAll(fiber?.lane)
+    );
+  });
+}
+
+// AIAgent-compatible scheduling hooks:
+// - When a pause_all human wait exists in a blocking lane (interactive/member), only allow background/collective lanes.
+export function createAiAgentSchedulerHooks<TSchema extends MailboxSchema>(): SchedulerHooks<TSchema> {
+  return {
+    filterCandidate: ({ state, fiber }) => {
+      if (!hasPauseAllHumanWaitInBlockingLane(state)) {
+        return true;
+      }
+      return isAllowedLaneDuringPauseAll((fiber as any)?.lane);
+    },
+  };
+}

package/src/orchestration/recovery.ts

@@ -0,0 +1,144 @@
+import type { MailboxSchema } from '../core/types';
+import type { FiberEffect, FiberId, FiberRecord, OrchestratorState, ReduceResult } from './types';
+
+function cloneFiberMap<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+): Record<FiberId, FiberRecord<TSchema>> {
+  return { ...state.fibers };
+}
+
+function buildDeadLetterEffects<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  fiber: FiberRecord<TSchema>,
+  reason: string,
+): FiberEffect<TSchema>[] {
+  const effects: FiberEffect<TSchema>[] = [
+    {
+      kind: 'dead_letter',
+      fiberId: fiber.id,
+      reason,
+    },
+  ];
+
+  const route = state.options.deadLetterFactory?.(fiber, reason);
+  if (route) {
+    effects.push({
+      kind: 'dead_letter',
+      fiberId: fiber.id,
+      reason,
+      to: route.to,
+      step: route.step,
+    });
+  }
+
+  return effects;
+}
+
+function computeRetryDelay(
+  retryDelayMs: number,
+  retryBackoffMultiplier: number,
+  attempts: number,
+): number {
+  const base = Math.max(0, retryDelayMs);
+  const multiplier = Math.max(1, retryBackoffMultiplier);
+  return Math.floor(base * Math.pow(multiplier, Math.max(0, attempts - 1)));
+}
+
+export function applyFailure<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  fiberId: FiberId,
+  now: number,
+  error: string,
+): ReduceResult<TSchema> {
+  const fiber = state.fibers[fiberId];
+  if (!fiber) {
+    return { state, effects: [] };
+  }
+
+  if (fiber.status === 'completed' || fiber.status === 'cancelled' || fiber.status === 'dead_letter') {
+    return { state, effects: [] };
+  }
+
+  const nextFibers = cloneFiberMap(state);
+
+  if (state.options.retryEnabled && fiber.attempts < fiber.maxAttempts) {
+    const nextAttempts = fiber.attempts + 1;
+    const delay = computeRetryDelay(
+      state.options.retryDelayMs,
+      state.options.retryBackoffMultiplier,
+      nextAttempts,
+    );
+    const updated: FiberRecord<TSchema> = {
+      ...fiber,
+      status: 'suspended',
+      waitingReason: 'retry_backoff',
+      suspendPolicy: undefined,
+      retryAt: now + delay,
+      timeoutAt: undefined,
+      attempts: nextAttempts,
+      lastError: error,
+      updatedAt: now,
+    };
+    nextFibers[fiberId] = updated;
+    return {
+      state: {
+        ...state,
+        fibers: nextFibers,
+      },
+      effects: [],
+    };
+  }
+
+  if (state.options.deadLetterEnabled) {
+    const updated: FiberRecord<TSchema> = {
+      ...fiber,
+      status: 'dead_letter',
+      waitingReason: undefined,
+      suspendPolicy: undefined,
+      retryAt: undefined,
+      lastError: error,
+      updatedAt: now,
+    };
+    nextFibers[fiberId] = updated;
+
+    const deadLetters = [
+      ...state.deadLetters,
+      {
+        fiberId: fiber.id,
+        actorId: fiber.actorId,
+        reason: error,
+        at: now,
+        attempts: fiber.attempts,
+        step: fiber.step,
+      },
+    ];
+
+    return {
+      state: {
+        ...state,
+        fibers: nextFibers,
+        deadLetters,
+      },
+      effects: buildDeadLetterEffects(state, updated, error),
+    };
+  }
+
+  const updated: FiberRecord<TSchema> = {
+    ...fiber,
+    status: 'failed',
+    waitingReason: undefined,
+    suspendPolicy: undefined,
+    retryAt: undefined,
+    lastError: error,
+    updatedAt: now,
+  };
+  nextFibers[fiberId] = updated;
+
+  return {
+    state: {
+      ...state,
+      fibers: nextFibers,
+    },
+    effects: [],
+  };
+}