depa-actor 0.1.0

package/src/orchestration/reducer.ts

@@ -0,0 +1,337 @@
+import type { MailboxSchema } from '../core/types';
+import { applyFailure } from './recovery';
+import {
+  DEFAULT_ORCHESTRATOR_OPTIONS,
+  type FiberAction,
+  type FiberId,
+  type FiberRecord,
+  type OrchestratorOptions,
+  type OrchestratorState,
+  type ReduceResult,
+  type SpawnFiberInput,
+  type SuspendPolicy,
+} from './types';
+
+function isTerminalStatus(status: FiberRecord<MailboxSchema>['status']): boolean {
+  return status === 'completed' || status === 'cancelled' || status === 'failed' || status === 'dead_letter';
+}
+
+function cloneFiberMap<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+): Record<FiberId, FiberRecord<TSchema>> {
+  return { ...state.fibers };
+}
+
+function upsertParentChildRelation<TSchema extends MailboxSchema>(
+  fibers: Record<FiberId, FiberRecord<TSchema>>,
+  fiber: SpawnFiberInput<TSchema>,
+  now: number,
+): void {
+  if (!fiber.parentId) {
+    return;
+  }
+  const parent = fibers[fiber.parentId];
+  if (!parent) {
+    return;
+  }
+
+  if (!parent.childIds.includes(fiber.id)) {
+    fibers[fiber.parentId] = {
+      ...parent,
+      childIds: [...parent.childIds, fiber.id],
+      updatedAt: now,
+    };
+  }
+}
+
+function createFiberRecord<TSchema extends MailboxSchema>(
+  input: SpawnFiberInput<TSchema>,
+  now: number,
+  order: number,
+  state: OrchestratorState<TSchema>,
+): FiberRecord<TSchema> {
+  const timeoutMs = input.timeoutMs ?? state.options.defaultTimeoutMs;
+  return {
+    id: input.id,
+    actorId: input.actorId,
+    parentId: input.parentId,
+    childIds: [],
+    lane: input.lane ?? 'default',
+    status: 'ready',
+    basePriority: input.basePriority,
+    age: 0,
+    attempts: 0,
+    maxAttempts: Math.max(0, input.maxAttempts ?? 0),
+    step: input.step,
+    waitingReason: undefined,
+    suspendPolicy: undefined,
+    timeoutMs: timeoutMs > 0 ? timeoutMs : undefined,
+    timeoutAt: undefined,
+    retryAt: undefined,
+    lastError: undefined,
+    order,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function createOrchestratorState<TSchema extends MailboxSchema>(
+  options?: Partial<OrchestratorOptions<TSchema>>,
+): OrchestratorState<TSchema> {
+  const raw = (options ?? {}) as Partial<OrchestratorOptions<TSchema>>;
+  const effectiveDefault: SuspendPolicy =
+    (raw.defaultSuspendPolicy as SuspendPolicy | undefined) ??
+    (DEFAULT_ORCHESTRATOR_OPTIONS.defaultSuspendPolicy as SuspendPolicy);
+
+  const base = {
+    ...DEFAULT_ORCHESTRATOR_OPTIONS,
+    ...raw,
+  } as OrchestratorOptions<TSchema>;
+
+  return {
+    options: {
+      ...base,
+      defaultSuspendPolicy: effectiveDefault,
+    },
+    fibers: {},
+    deadLetters: [],
+    sequence: 0,
+  };
+}
+
+function applyTick<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  now: number,
+): ReduceResult<TSchema> {
+  let nextState = state;
+  let aggregatedEffects: ReduceResult<TSchema>['effects'] = [];
+
+  const ids = Object.keys(state.fibers);
+  for (const id of ids) {
+    const fiber = nextState.fibers[id];
+    if (!fiber) {
+      continue;
+    }
+    if (isTerminalStatus(fiber.status)) {
+      continue;
+    }
+
+    if (
+      nextState.options.timeoutEnabled &&
+      fiber.timeoutAt !== undefined &&
+      now >= fiber.timeoutAt &&
+      (fiber.status === 'running' || fiber.status === 'ready' || fiber.status === 'suspended')
+    ) {
+      const timed = applyFailure(nextState, id, now, 'timeout');
+      nextState = timed.state;
+      aggregatedEffects = [...aggregatedEffects, ...timed.effects];
+      continue;
+    }
+
+    const iter = nextState.fibers[id];
+    if (
+      iter &&
+      iter.status === 'suspended' &&
+      iter.waitingReason === 'retry_backoff' &&
+      iter.retryAt !== undefined &&
+      now >= iter.retryAt
+    ) {
+      nextState = {
+        ...nextState,
+        fibers: {
+          ...nextState.fibers,
+          [id]: {
+            ...iter,
+            status: 'ready',
+            waitingReason: undefined,
+            retryAt: undefined,
+            timeoutAt: undefined,
+            updatedAt: now,
+          },
+        },
+      };
+    }
+  }
+
+  return {
+    state: nextState,
+    effects: aggregatedEffects,
+  };
+}
+
+export function reduceOrchestrator<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  action: FiberAction<TSchema>,
+): ReduceResult<TSchema> {
+  if (action.type === 'tick') {
+    return applyTick(state, action.now);
+  }
+
+  if (action.type === 'spawn') {
+    const nextSequence = state.sequence + 1;
+    const nextFibers = cloneFiberMap(state);
+    const record = createFiberRecord(action.fiber, action.now, nextSequence, state);
+    nextFibers[action.fiber.id] = record;
+    upsertParentChildRelation(nextFibers, action.fiber, action.now);
+    return {
+      state: {
+        ...state,
+        sequence: nextSequence,
+        fibers: nextFibers,
+      },
+      effects: [],
+    };
+  }
+
+  const current = state.fibers[action.fiberId];
+  if (!current) {
+    return { state, effects: [] };
+  }
+
+  if (action.type === 'yield') {
+    if (isTerminalStatus(current.status)) {
+      return { state, effects: [] };
+    }
+    return {
+      state: {
+        ...state,
+        fibers: {
+          ...state.fibers,
+          [action.fiberId]: {
+            ...current,
+            status: 'ready',
+            waitingReason: undefined,
+            suspendPolicy: undefined,
+            timeoutAt: undefined,
+            step: action.nextStep ?? current.step,
+            updatedAt: action.now,
+          },
+        },
+      },
+      effects: [],
+    };
+  }
+
+  if (action.type === 'suspend') {
+    if (isTerminalStatus(current.status)) {
+      return { state, effects: [] };
+    }
+
+    const effectivePolicy: SuspendPolicy =
+      (action.suspendPolicy as SuspendPolicy | undefined) ??
+      (state.options.defaultSuspendPolicy as SuspendPolicy | undefined) ??
+      'continue_others';
+    return {
+      state: {
+        ...state,
+        fibers: {
+          ...state.fibers,
+          [action.fiberId]: {
+            ...current,
+            status: 'suspended',
+            waitingReason: action.reason,
+            suspendPolicy: effectivePolicy,
+            timeoutAt: undefined,
+            updatedAt: action.now,
+          },
+        },
+      },
+      effects: [],
+    };
+  }
+
+  if (action.type === 'resume') {
+    if (isTerminalStatus(current.status)) {
+      return { state, effects: [] };
+    }
+    return {
+      state: {
+        ...state,
+        fibers: {
+          ...state.fibers,
+          [action.fiberId]: {
+            ...current,
+            status: 'ready',
+            waitingReason: undefined,
+            suspendPolicy: undefined,
+            retryAt: undefined,
+            timeoutAt: undefined,
+            step: action.nextStep ?? current.step,
+            updatedAt: action.now,
+          },
+        },
+      },
+      effects: [],
+    };
+  }
+
+  if (action.type === 'complete') {
+    return {
+      state: {
+        ...state,
+        fibers: {
+          ...state.fibers,
+          [action.fiberId]: {
+            ...current,
+            status: 'completed',
+            waitingReason: undefined,
+            suspendPolicy: undefined,
+            timeoutAt: undefined,
+            updatedAt: action.now,
+          },
+        },
+      },
+      effects: [],
+    };
+  }
+
+  if (action.type === 'fail') {
+    return applyFailure(state, action.fiberId, action.now, action.error);
+  }
+
+  if (action.type === 'cancel') {
+    const nextFibers = cloneFiberMap(state);
+    const queue = [action.fiberId];
+    const seen = new Set<string>();
+
+    while (queue.length > 0) {
+      const id = queue.shift()!;
+      if (seen.has(id)) {
+        continue;
+      }
+      seen.add(id);
+
+      const item = nextFibers[id];
+      if (!item) {
+        continue;
+      }
+
+      nextFibers[id] = {
+        ...item,
+        status: 'cancelled',
+        waitingReason: undefined,
+        suspendPolicy: undefined,
+        timeoutAt: undefined,
+        retryAt: undefined,
+        lastError: action.reason,
+        updatedAt: action.now,
+      };
+
+      if (action.propagateToChildren) {
+        for (const childId of item.childIds) {
+          queue.push(childId);
+        }
+      }
+    }
+
+    return {
+      state: {
+        ...state,
+        fibers: nextFibers,
+      },
+      effects: [],
+    };
+  }
+
+  return { state, effects: [] };
+}

package/src/orchestration/runtimeAdapter.ts

@@ -0,0 +1,19 @@
+import type { MailboxSchema } from '../core/types';
+import type { ActorRuntime } from '../runtime/ActorRuntime';
+import type { FiberEffect } from './types';
+
+export function dispatchEffects<TRuntime, TSchema extends MailboxSchema>(
+  runtime: ActorRuntime<TRuntime, TSchema>,
+  effects: FiberEffect<TSchema>[],
+  senderId?: string,
+): void {
+  const from = senderId ?? '__fiber_scheduler__';
+  for (const effect of effects) {
+    if (effect.kind === 'send') {
+      runtime.sendFrom(from, effect.to, effect.step.tag, effect.step.payload);
+    }
+    if (effect.kind === 'dead_letter' && effect.to && effect.step) {
+      runtime.sendFrom(from, effect.to, effect.step.tag, effect.step.payload);
+    }
+  }
+}

package/src/orchestration/scheduler.ts

@@ -0,0 +1,111 @@
+import type { MailboxSchema } from '../core/types';
+import type { FiberEffect, FiberId, FiberRecord, OrchestratorState } from './types';
+
+export interface ScheduleResult<TSchema extends MailboxSchema> {
+  state: OrchestratorState<TSchema>;
+  effects: FiberEffect<TSchema>[];
+  selectedFiberId?: FiberId;
+}
+
+function isSchedulable<TSchema extends MailboxSchema>(fiber: FiberRecord<TSchema>): boolean {
+  return fiber.status === 'ready';
+}
+
+export function computeEffectivePriority<TSchema extends MailboxSchema>(
+  fiber: FiberRecord<TSchema>,
+  agingStep: number,
+): number {
+  return fiber.basePriority - fiber.age * Math.max(0, agingStep);
+}
+
+export function selectNextFiberId<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  now?: number,
+): FiberId | undefined {
+  const hooks = state.options.schedulerHooks;
+  const selectionNow = typeof now === 'number' ? now : Date.now();
+  let candidates = Object.values(state.fibers).filter(isSchedulable);
+
+  if (hooks?.filterCandidates) {
+    candidates = hooks.filterCandidates({ state, candidates, now: selectionNow });
+  } else if (hooks?.filterCandidate) {
+    const f = hooks.filterCandidate;
+    candidates = candidates.filter(fiber => f({ state, fiber, now: selectionNow }));
+  }
+
+  if (candidates.length === 0) {
+    return undefined;
+  }
+
+  const agingStep = state.options.agingStep;
+  candidates.sort((a, b) => {
+    const pa = computeEffectivePriority(a, agingStep);
+    const pb = computeEffectivePriority(b, agingStep);
+    if (pa !== pb) {
+      return pa - pb;
+    }
+    return a.order - b.order;
+  });
+
+  return candidates[0]?.id;
+}
+
+export function scheduleOne<TSchema extends MailboxSchema>(
+  state: OrchestratorState<TSchema>,
+  now: number,
+): ScheduleResult<TSchema> {
+  const selectedFiberId = selectNextFiberId(state, now);
+  if (!selectedFiberId) {
+    return { state, effects: [] };
+  }
+
+  const selected = state.fibers[selectedFiberId];
+  if (!selected) {
+    return { state, effects: [] };
+  }
+
+  const timeoutMs = selected.timeoutMs ?? state.options.defaultTimeoutMs;
+  const timeoutAt = state.options.timeoutEnabled && timeoutMs > 0 ? now + timeoutMs : undefined;
+
+  const nextFibers: Record<FiberId, FiberRecord<TSchema>> = { ...state.fibers };
+  for (const [id, fiber] of Object.entries(state.fibers)) {
+    if (id === selectedFiberId) {
+      nextFibers[id] = {
+        ...fiber,
+        status: 'running',
+        age: 0,
+        timeoutAt,
+        updatedAt: now,
+      };
+      continue;
+    }
+
+    if (fiber.status === 'ready') {
+      nextFibers[id] = {
+        ...fiber,
+        age: fiber.age + Math.max(0, state.options.agingStep),
+        updatedAt: now,
+      };
+    }
+  }
+
+  const effects: FiberEffect<TSchema>[] = [];
+  const withStep = nextFibers[selectedFiberId];
+  if (withStep?.step) {
+    effects.push({
+      kind: 'send',
+      fiberId: selectedFiberId,
+      to: withStep.actorId,
+      step: withStep.step,
+    });
+  }
+
+  return {
+    state: {
+      ...state,
+      fibers: nextFibers,
+    },
+    effects,
+    selectedFiberId,
+  };
+}

package/src/orchestration/types.ts

@@ -0,0 +1,159 @@
+import type { MailboxSchema } from '../core/types';
+
+export type FiberId = string;
+
+export type FiberStatus =
+  | 'ready'
+  | 'running'
+  | 'suspended'
+  | 'completed'
+  | 'cancelled'
+  | 'failed'
+  | 'dead_letter';
+
+// Core should not bake in domain-specific waiting reasons.
+export type FiberWaitingReason = string;
+
+export type SuspendPolicy = 'continue_others' | 'pause_all';
+
+// Core keeps the lane mechanism but treats lane ids as opaque.
+export type FiberLane = string;
+
+export type SchedulerFilterCandidate<TSchema extends MailboxSchema> = (args: {
+  state: OrchestratorState<TSchema>;
+  fiber: FiberRecord<TSchema>;
+  now: number;
+}) => boolean;
+
+export type SchedulerFilterCandidates<TSchema extends MailboxSchema> = (args: {
+  state: OrchestratorState<TSchema>;
+  candidates: Array<FiberRecord<TSchema>>;
+  now: number;
+}) => Array<FiberRecord<TSchema>>;
+
+export interface SchedulerHooks<TSchema extends MailboxSchema> {
+  filterCandidate?: SchedulerFilterCandidate<TSchema>;
+  filterCandidates?: SchedulerFilterCandidates<TSchema>;
+}
+
+export type FiberStep<TSchema extends MailboxSchema> = {
+  [K in keyof TSchema & string]: {
+    tag: K;
+    payload: TSchema[K];
+  }
+}[keyof TSchema & string];
+
+export interface FiberRecord<TSchema extends MailboxSchema> {
+  id: FiberId;
+  actorId: string;
+  parentId?: FiberId;
+  childIds: FiberId[];
+  lane: FiberLane;
+  status: FiberStatus;
+  basePriority: number;
+  age: number;
+  attempts: number;
+  maxAttempts: number;
+  step?: FiberStep<TSchema>;
+  waitingReason?: FiberWaitingReason;
+  suspendPolicy?: SuspendPolicy;
+  timeoutMs?: number;
+  timeoutAt?: number;
+  retryAt?: number;
+  lastError?: string;
+  order: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface SpawnFiberInput<TSchema extends MailboxSchema> {
+  id: FiberId;
+  actorId: string;
+  parentId?: FiberId;
+  basePriority: number;
+  lane?: FiberLane;
+  maxAttempts?: number;
+  step?: FiberStep<TSchema>;
+  timeoutMs?: number;
+}
+
+export interface DeadLetterRecord<TSchema extends MailboxSchema> {
+  fiberId: FiberId;
+  actorId: string;
+  reason: string;
+  at: number;
+  attempts: number;
+  step?: FiberStep<TSchema>;
+}
+
+export interface OrchestratorOptions<TSchema extends MailboxSchema> {
+  senderId: string;
+  agingStep: number;
+  defaultSuspendPolicy: SuspendPolicy;
+  schedulerHooks?: SchedulerHooks<TSchema>;
+  timeoutEnabled: boolean;
+  defaultTimeoutMs: number;
+  retryEnabled: boolean;
+  retryDelayMs: number;
+  retryBackoffMultiplier: number;
+  deadLetterEnabled: boolean;
+  deadLetterFactory?: (
+    fiber: FiberRecord<TSchema>,
+    reason: string,
+  ) => { to: string; step: FiberStep<TSchema> } | null;
+}
+
+export interface OrchestratorState<TSchema extends MailboxSchema> {
+  options: OrchestratorOptions<TSchema>;
+  fibers: Record<FiberId, FiberRecord<TSchema>>;
+  deadLetters: DeadLetterRecord<TSchema>[];
+  sequence: number;
+}
+
+export type FiberAction<TSchema extends MailboxSchema> =
+  | { type: 'spawn'; fiber: SpawnFiberInput<TSchema>; now: number }
+  | { type: 'yield'; fiberId: FiberId; now: number; nextStep?: FiberStep<TSchema> }
+  | {
+      type: 'suspend';
+      fiberId: FiberId;
+      now: number;
+      reason: FiberWaitingReason;
+      suspendPolicy?: SuspendPolicy;
+    }
+  | { type: 'resume'; fiberId: FiberId; now: number; nextStep?: FiberStep<TSchema> }
+  | { type: 'complete'; fiberId: FiberId; now: number }
+  | { type: 'fail'; fiberId: FiberId; now: number; error: string }
+  | { type: 'cancel'; fiberId: FiberId; now: number; reason: string; propagateToChildren?: boolean }
+  | { type: 'tick'; now: number };
+
+export type FiberEffect<TSchema extends MailboxSchema> =
+  | {
+      kind: 'send';
+      fiberId: FiberId;
+      to: string;
+      step: FiberStep<TSchema>;
+    }
+  | {
+      kind: 'dead_letter';
+      fiberId: FiberId;
+      reason: string;
+      to?: string;
+      step?: FiberStep<TSchema>;
+    };
+
+export interface ReduceResult<TSchema extends MailboxSchema> {
+  state: OrchestratorState<TSchema>;
+  effects: FiberEffect<TSchema>[];
+}
+
+export const DEFAULT_ORCHESTRATOR_OPTIONS: Omit<OrchestratorOptions<MailboxSchema>, 'deadLetterFactory'> = {
+  senderId: '__fiber_scheduler__',
+  agingStep: 1,
+  defaultSuspendPolicy: 'continue_others',
+  timeoutEnabled: false,
+  defaultTimeoutMs: 0,
+  retryEnabled: false,
+  retryDelayMs: 0,
+  retryBackoffMultiplier: 1,
+  deadLetterEnabled: false,
+};