depa-actor 0.1.0

package/src/pipeline/ActorPipeline.ts

@@ -0,0 +1,132 @@
+/**
+ * depa-actor — ActorPipeline
+ *
+ * Adapts the DOP 6-step pipeline (from depa-processor) to actor context.
+ *
+ * Mapping:
+ *   OuterRuntime = ActorSelf
+ *   OuterInput   = envelope payload
+ *   OuterConfig  = actor state
+ *
+ * createPipelineHandler() wraps a pipeline definition into an ActorHandler.
+ */
+
+import type {
+  MailboxSchema,
+  ActorSelf,
+  ActorHandler,
+} from '../core/types';
+
+// ─── Pipeline Adapter Types ──────────────────────────────────────────
+
+export type PipelineDerivedAdapter<
+  TRuntime, TSchema extends MailboxSchema, TState, TDerived,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  payload: TSchema[keyof TSchema & string],
+  state: TState,
+) => TDerived;
+
+export type PipelineInnerRuntimeAdapter<
+  TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerRuntime,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  payload: TSchema[keyof TSchema & string],
+  state: TState,
+  derived: TDerived,
+) => TInnerRuntime;
+
+export type PipelineInnerInputAdapter<
+  TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerInput,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  payload: TSchema[keyof TSchema & string],
+  state: TState,
+  derived: TDerived,
+) => TInnerInput;
+
+export type PipelineInnerConfigAdapter<
+  TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerConfig,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  payload: TSchema[keyof TSchema & string],
+  state: TState,
+  derived: TDerived,
+) => TInnerConfig;
+
+export type PipelineCoreLogic<TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput> = (
+  runtime: TInnerRuntime,
+  input: TInnerInput,
+  config: TInnerConfig,
+) => TInnerOutput | Promise<TInnerOutput>;
+
+export type PipelineOutputAdapter<
+  TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerOutput,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  payload: TSchema[keyof TSchema & string],
+  state: TState,
+  derived: TDerived,
+  innerOutput: TInnerOutput,
+) => void | Promise<void>;
+
+// ─── Pipeline Definition ─────────────────────────────────────────────
+
+export interface ActorPipelineDef<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+  TDerived,
+  TInnerRuntime,
+  TInnerInput,
+  TInnerConfig,
+  TInnerOutput,
+> {
+  computeDerived: PipelineDerivedAdapter<TRuntime, TSchema, TState, TDerived>;
+  innerRuntime: PipelineInnerRuntimeAdapter<TRuntime, TSchema, TState, TDerived, TInnerRuntime>;
+  innerInput: PipelineInnerInputAdapter<TRuntime, TSchema, TState, TDerived, TInnerInput>;
+  innerConfig: PipelineInnerConfigAdapter<TRuntime, TSchema, TState, TDerived, TInnerConfig>;
+  coreLogic: PipelineCoreLogic<TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput>;
+  output: PipelineOutputAdapter<TRuntime, TSchema, TState, TDerived, TInnerOutput>;
+}
+
+// ─── createPipelineHandler ───────────────────────────────────────────
+
+export function createPipelineHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+  TDerived,
+  TInnerRuntime,
+  TInnerInput,
+  TInnerConfig,
+  TInnerOutput,
+>(
+  pipeline: ActorPipelineDef<
+    TRuntime, TSchema, TState, TDerived,
+    TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput
+  >,
+): ActorHandler<TRuntime, TSchema, TState> {
+  return async (self, envelope) => {
+    const payload = envelope.payload;
+    const state = self.state;
+
+    // Step 1: Compute derived
+    const derived = pipeline.computeDerived(self, payload, state);
+
+    // Step 2: Transform runtime
+    const innerRuntime = pipeline.innerRuntime(self, payload, state, derived);
+
+    // Step 3: Transform input
+    const innerInput = pipeline.innerInput(self, payload, state, derived);
+
+    // Step 4: Transform config
+    const innerConfig = pipeline.innerConfig(self, payload, state, derived);
+
+    // Step 5: Core logic
+    const innerOutput = await pipeline.coreLogic(innerRuntime, innerInput, innerConfig);
+
+    // Step 6: Output (side effects on actor state / send messages)
+    await pipeline.output(self, payload, state, derived, innerOutput);
+  };
+}

package/src/runtime/ActorRuntime.ts

@@ -0,0 +1,119 @@
+/**
+ * depa-actor — ActorRuntime
+ *
+ * Lifecycle and plugin layer over ActorSystem.
+ * ActorSystem = engine, ActorRuntime = managed environment.
+ *
+ * Future AiAgentVm will hold an ActorRuntime instance.
+ */
+
+import type {
+  MailboxSchema,
+  ActorDef,
+  ActorRef,
+  ActorLogEntry,
+} from '../core/types';
+import { ActorSystem } from '../core/ActorSystem';
+
+// ─── Plugin ──────────────────────────────────────────────────────────
+
+export interface ActorPlugin<TRuntime, TSchema extends MailboxSchema> {
+  name: string;
+  onRegister?: (id: string, def: ActorDef<TRuntime, TSchema, unknown>) => void;
+  onUnregister?: (id: string) => void;
+  onLog?: (entry: ActorLogEntry<TSchema>) => void;
+}
+
+// ─── ActorRuntime ────────────────────────────────────────────────────
+
+export class ActorRuntime<TRuntime, TSchema extends MailboxSchema> {
+  readonly system: ActorSystem<TRuntime, TSchema>;
+  private plugins: ActorPlugin<TRuntime, TSchema>[] = [];
+  private facets = new Map<string, unknown>();
+
+  constructor(
+    getRuntime: () => TRuntime,
+    plugins?: ActorPlugin<TRuntime, TSchema>[],
+  ) {
+    this.plugins = plugins ?? [];
+
+    this.system = new ActorSystem<TRuntime, TSchema>(
+      getRuntime,
+      (entry) => this.handleLog(entry),
+    );
+  }
+
+  // ── Plugin management ──
+
+  addPlugin(plugin: ActorPlugin<TRuntime, TSchema>): void {
+    this.plugins.push(plugin);
+  }
+
+  hasFacet(name: string): boolean {
+    return this.facets.has(name);
+  }
+
+  getFacet<TFacet>(name: string): TFacet | undefined {
+    return this.facets.get(name) as TFacet | undefined;
+  }
+
+  setFacet<TFacet>(name: string, facet: TFacet): TFacet {
+    this.facets.set(name, facet);
+    return facet;
+  }
+
+  ensureFacet<TFacet>(name: string, create: () => TFacet): TFacet {
+    const existing = this.facets.get(name) as TFacet | undefined;
+    if (existing !== undefined) {
+      return existing;
+    }
+    const created = create();
+    this.facets.set(name, created);
+    return created;
+  }
+
+  // ── Delegated API (convenience) ──
+
+  register<TState = void>(id: string, def: ActorDef<TRuntime, TSchema, TState>): void {
+    this.system.register(id, def);
+    for (const p of this.plugins) {
+      p.onRegister?.(id, def as ActorDef<TRuntime, TSchema, unknown>);
+    }
+  }
+
+  unregister(id: string): void {
+    this.system.unregister(id);
+    for (const p of this.plugins) {
+      p.onUnregister?.(id);
+    }
+  }
+
+  sendFrom<TTag extends keyof TSchema & string>(
+    from: string,
+    to: string,
+    tag: TTag,
+    payload: TSchema[TTag],
+  ): void {
+    this.system.sendFrom(from, to, tag, payload);
+  }
+
+  refFrom(from: string, to: string): ActorRef<TSchema> | undefined {
+    return this.system.refFrom(from, to);
+  }
+
+  ids(): string[] {
+    return this.system.ids();
+  }
+
+  has(id: string): boolean {
+    return this.system.has(id);
+  }
+
+  // ── Internal ──
+
+  private handleLog(entry: ActorLogEntry<TSchema>): void {
+    for (const p of this.plugins) {
+      p.onLog?.(entry);
+    }
+  }
+}

package/src/runtime/completion.ts

@@ -0,0 +1,86 @@
+export type CompletionWaiter<TResult> = (result: TResult) => void;
+
+export class CompletionSignalRegistry<TKey extends string, TResult> {
+  private readonly waiters = new Map<TKey, Set<CompletionWaiter<TResult>>>();
+
+  subscribe(key: TKey, waiter: CompletionWaiter<TResult>): () => void {
+    const current = this.waiters.get(key) ?? new Set<CompletionWaiter<TResult>>();
+    current.add(waiter);
+    this.waiters.set(key, current);
+    return () => {
+      const next = this.waiters.get(key);
+      if (!next) {
+        return;
+      }
+      next.delete(waiter);
+      if (next.size === 0) {
+        this.waiters.delete(key);
+      }
+    };
+  }
+
+  resolve(key: TKey, result: TResult): void {
+    const waiters = this.waiters.get(key);
+    if (!waiters || waiters.size === 0) {
+      return;
+    }
+    this.waiters.delete(key);
+    for (const waiter of Array.from(waiters)) {
+      waiter(result);
+    }
+  }
+
+  has(key: TKey): boolean {
+    return (this.waiters.get(key)?.size ?? 0) > 0;
+  }
+
+  count(key: TKey): number {
+    return this.waiters.get(key)?.size ?? 0;
+  }
+
+  clear(key?: TKey): void {
+    if (key !== undefined) {
+      this.waiters.delete(key);
+      return;
+    }
+    this.waiters.clear();
+  }
+}
+
+export function createCompletionSignalRegistry<TKey extends string, TResult>(): CompletionSignalRegistry<TKey, TResult> {
+  return new CompletionSignalRegistry<TKey, TResult>();
+}
+
+export class CompletionBindingRegistry<TKey extends string, TBinding> {
+  private readonly bindings: Record<TKey, TBinding>;
+
+  constructor(initial?: Record<TKey, TBinding>) {
+    this.bindings = Object.assign(Object.create(null) as Record<TKey, TBinding>, initial ?? {});
+  }
+
+  get(key: TKey): TBinding | undefined {
+    return this.bindings[key];
+  }
+
+  set(key: TKey, binding: TBinding): void {
+    this.bindings[key] = binding;
+  }
+
+  delete(key: TKey): void {
+    delete this.bindings[key];
+  }
+
+  has(key: TKey): boolean {
+    return key in this.bindings;
+  }
+
+  snapshot(): Record<TKey, TBinding> {
+    return { ...this.bindings };
+  }
+}
+
+export function createCompletionBindingRegistry<TKey extends string, TBinding>(
+  initial?: Record<TKey, TBinding>,
+): CompletionBindingRegistry<TKey, TBinding> {
+  return new CompletionBindingRegistry<TKey, TBinding>(initial);
+}

package/src/runtime/indexing.ts

@@ -0,0 +1,39 @@
+export class RuntimeIndexHook<TKey extends string, TValue> {
+  private readonly entries = new Map<TKey, TValue>();
+
+  constructor(initial?: Record<TKey, TValue>) {
+    for (const [key, value] of Object.entries(initial ?? {}) as Array<[TKey, TValue]>) {
+      this.entries.set(key, value);
+    }
+  }
+
+  get(key: TKey): TValue | undefined {
+    return this.entries.get(key);
+  }
+
+  set(key: TKey, value: TValue): void {
+    this.entries.set(key, value);
+  }
+
+  delete(key: TKey): void {
+    this.entries.delete(key);
+  }
+
+  has(key: TKey): boolean {
+    return this.entries.has(key);
+  }
+
+  values(): TValue[] {
+    return Array.from(this.entries.values());
+  }
+
+  snapshot(): Record<TKey, TValue> {
+    return Object.fromEntries(this.entries.entries()) as Record<TKey, TValue>;
+  }
+}
+
+export function createRuntimeIndexHook<TKey extends string, TValue>(
+  initial?: Record<TKey, TValue>,
+): RuntimeIndexHook<TKey, TValue> {
+  return new RuntimeIndexHook<TKey, TValue>(initial);
+}

package/src/runtime/snapshot.ts

@@ -0,0 +1,91 @@
+export type SnapshotRecoveryState = {
+  restoredFromSnapshot: boolean;
+  snapshotVersion?: number;
+  restoredAt?: number;
+};
+
+export type RuntimeSnapshotManifestBase = {
+  version: number;
+  createdAt: string;
+  updatedAt: string;
+  actorKeys: string[];
+  fiberIds: string[];
+  indexFiles: string[];
+  derivedIndexFiles?: string[];
+  savedAt?: number;
+  vmFile: string;
+  actorFiles: Record<string, string>;
+  fiberFiles: Record<string, string>;
+};
+
+export type RuntimeRootSnapshotBase = {
+  version: number;
+  controlActorKey: string;
+  actorKeys: string[];
+  updatedAt: string;
+  recovery?: SnapshotRecoveryState;
+};
+
+export type ActorSnapshotBase<TActorType extends string = string> = {
+  version: number;
+  key: string;
+  id: string;
+  type: TActorType;
+  parentKey?: string;
+  updatedAt?: string;
+  recovery?: SnapshotRecoveryState;
+};
+
+export type FiberSnapshotBase = {
+  version: number;
+  fiberId: string;
+  actorKey?: string;
+  actorId?: string;
+  parentFiberId?: string;
+  status?: string;
+  lane?: string;
+  workloadKind?: string;
+  kind?: string;
+  waitingReason?: string | null;
+  createdAt?: number;
+  lastRunAt?: number | null;
+  lastYieldAt?: number | null;
+  resumeMetadata?: Record<string, unknown> | null;
+  updatedAt?: string;
+  workload?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export interface SnapshotCodec<TState, TSnapshot> {
+  serialize: (state: TState) => TSnapshot;
+  hydrate: (snapshot: TSnapshot) => TState;
+}
+
+export interface RecoveryHooks<TState, TSnapshot> {
+  beforeSerialize?: (state: TState) => TState;
+  beforeHydrate?: (snapshot: TSnapshot) => TSnapshot;
+  afterHydrate?: (state: TState) => TState;
+}
+
+export interface PersistenceEffectPort<TManifest, TSnapshotState> {
+  save: (params: { manifest: TManifest; state: TSnapshotState }) => Promise<void>;
+  load: () => Promise<{ manifest: TManifest; state: TSnapshotState } | null>;
+}
+
+export function createSnapshotCodec<TState, TSnapshot>(
+  codec: SnapshotCodec<TState, TSnapshot>,
+): SnapshotCodec<TState, TSnapshot> {
+  return codec;
+}
+
+export function createRecoveryHooks<TState, TSnapshot>(
+  hooks: RecoveryHooks<TState, TSnapshot>,
+): RecoveryHooks<TState, TSnapshot> {
+  return hooks;
+}
+
+export function createPersistenceEffectPort<TManifest, TSnapshotState>(
+  port: PersistenceEffectPort<TManifest, TSnapshotState>,
+): PersistenceEffectPort<TManifest, TSnapshotState> {
+  return port;
+}